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About This Guide 


The Nsure? Identity Manager Driver for Java" Database Connectivity (JDBC) provides a generic 
solution for synchronizing data between the Identity Vault and relational databases. 


This guide provides an overview of the driver’s technology as well as configuration instructions. 


Additional Documentation 


For documentation on using Identity Manager and the other drivers, see the Identity Manager 
Documentation Web site (http://www.novell.com/documentation/lg/dirxmldrivers). 


Documentation Updates 


For the most recent version of this document, see the Identity Manager Documentation Web site 
(http: //www.novell.com/documentation/lg/dirxmldrivers/index.html). 


Documentation Conventions 


In this documentation, a greater-than symbol (>) is used to separate actions within a step and items 
within a cross-reference path. 


A trademark symbol E TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party 
trademark. 


User Comments 


We want to hear your comments and suggestions about this manual and the other documentation 
included with Novell Nsure™ Identity Manager. Please use the User Comment feature at the 
bottom of each page of the online documentation, or go to www.novell.com/documentation/ 
feedback.html and enter your comments there. 
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Overview 


Introducing the Nsure Identity Manager Driver 
for JDBC 


The Nsure™ Identity Manager Driver for Java DataBase Connectivity (JDBC), subsequently 
referred to as the driver, provides a generic solution for synchronizing data between Identity 
Manager and JDBC-accessible relational databases. 


The principal value of this driver resides in its generic nature. Unlike most drivers that interface 
with a single application, this driver can interface with most relational databases and database- 
hosted applications. 


In this section, you will find information on the following topics: 


+ 


+ 


+ 


New Features 


Driver Features 


“New Features” on page 11 

“Driver Concepts” on page 12 

“Database Concepts” on page 14 

“Data Synchronization Models” on page 18 


“Triggerless Publication” on page 21 


This section includes information about the driver’s new features. 


Numerous publication enhancements: 
+ Publication without triggers. See “Triggerless Publication” on page 21. 
+ Daily publication. See parameter “Publication time of day” on page 63. 
+ Future event processing. See parameter “Enable future event processing?” on page 62. 
+ Batch processing. See parameter “Batch size” on page 64. 
Expanded database support. See “Supported Databases” on page 111. 
Enhanced support for database time types. See parameter “Time syntax” on page 39. 
Enhanced ease of use. See “Smart Configuration” on page 33. 


Schema filtering. See parameters “Include filter expression” on page 41 and “Exclude filter 
expression” on page 42. 


Extended view support. See “Direct Synchronization” on page 74. 
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+ Enhanced support for third-party driver encryption mechanisms. See parameter "Connection 
properties” on page 43. 


+ Password modify and check support. 


+ Improved driver configuration/database SQL scripts. 


Identity Manager New Features 


For more information on the new features in Identity Manager, refer to the Nsure Identity Manager 
2 Administration Guide (http://www.novell.com/documentation/lg/dirxml120/admin/data/ 
alxnk27.html). 


Driver Concepts 
The following are some important terms and concepts you should know before installing and 
configuring the driver: 
+ “JDBC” on page 12 
+ “Identity Manager Driver for JDBC” on page 12 
+ “Third-Party JDBC Driver” on page 13 
+ “Identity Vault” on page 13 
+ “Directory Schema” on page 13 
+ “Application Schema” on page 13 
+ “Database Schema” on page 13 
+ “Synchronization Schema” on page 14 
+ “Logical Database Class” on page 14 
+ “XDS” on page 14 


JDBC 


An acronym that stands for Java DataBase Connectivity. JDBC is a cross-platform database 
interface standard developed by Sun Microsystems. Most enterprise database vendors provide a 
unique implementation of the JDBC interface. 


There are current three versions of the JDBC interface: JDBC 1 (Java 1.0), JDBC 2 (Java 1.2 or 
1.3) and JDBC 3 (Java 1.4 or 1.5). This product primarily uses the JDBC 1 interface, although it 
will use more advanced features when supported by third-party JDBC drivers. 


Identity Manager Driver for JDBC 


An Identity Manager driver that uses the JDBC interface to synchronize data and identities 
between Identity Manager and relational databases. The driver consists of four jar files: 
JDBCShim. jar, JDBCUtil. jar, JDBCConfig. jar and CommonDriverShim. jar. In 
addition to these files, you need a third-party JDBC driver to communicate with each individual 
database. 


12 IDM Driver for JDBC Implementation Guide 


Third-Party JDBC Driver 


One of the numerous JDBC interface implementations used by the driver to communicate with a 
particular database. For example, classes12.zip is one of the Oracle" JDBC drivers. Different 
third-party JDBC drivers implement different portions of the JDBC interface specification and 
implement the interface in a relatively consistent manner. 


The following illustration indicates the relationship between the Identity Manager Driver for 
JDBC and third-party JDBC drivers. 


IDM JDBC DRIVER > 
Interface 


Database 


Identity Vault 


The datastore used by Identity Manager: Novell® eDirectory™. 


Directory Schema 


The set of object classes and attributes in the directory. For example, the eDirectory User class and 
Given Name attribute are part of the eDirectory schema. 


Application Schema 


The set of classes and attributes in an application. Because databases have no concept of classes 
or attributes, the driver maps eDirectory classes to tables or views and maps eDirectory attributes 
to columns. 


Database Schema 


Schema is essentially synonymous with ownership. A database schema consists of database 
objects (tables, views, triggers, stored procedures, functions, etc.) owned by a database user. In the 
context of this driver, schema is useful for database scoping (that is, reducing the number of 
database objects visible to the driver at runtime). 
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Ownership is often expressed using a qualified dot notation such as indirect.usr, where 
indirect is the name of the database user that owns the table usr. All of the database objects 
owned by indirect constitute the indirect database schema. 


Synchronization Schema 


The database schema visible to the driver at runtime. 


Logical Database Class 


The set of tables or view used to represent an eDirectory class in a database. 


XDS 


The flavor of XML used by Identity Manager. 


Database Concepts 


In this section, you will learn about the following important database concepts: 
+ "Database Schema” on page 13 
+ "Structured Query Language” on page 14 
+ “Data Manipulation Language” on page 14 
+ “Data Definition Language” on page 15 
+ “View” on page 15 
+ “Identity Columns/Sequences” on page 15 
+ “Transaction” on page 16 
+ “Stored Procedures or Functions” on page 16 
* “Trigger” on page 17 
+ “Instead-Of-Trigger” on page 17 


Structured Query Language 


Structured Query Language (SQL) is the language used to query and manipulate data in relational 
databases. 


Data Manipulation Language 


Data Manipulation Language (DML) statements are highly standardized SQL statements that 
manipulate database data. DML statements are essentially the same regardless of the database you 
use. This product is essentially DML-based. It maps Identity Manager events expressed as XDS 
XML to standardized DML statements. 


The following example shows several DML statements: 


SELECT * FROM usr; 
INSERT INTO usr(lname) VALUES (’Doe’); 
UPDATE usr SET fname = ”John' WHERE idu = 1; 
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Data Definition Language 


View 


Data Definition Language (DDL) statements manipulate database objects such as tables, indexes, 
user accounts, and so forth. DDL statements are proprietary and differ substantially between 
databases. Even though this product is DML-based, DDL statements can be embedded in XDS 
events. For additional information, refer to “Embedding SQL Statements in XDS Events” on 
page 87. 


The following examples show several DDL statements: 


CREATE TABLE usr 
( 


idu INTEGER, 

fname VARCHAR2 (64), 

lname VARCHAR2 (64) 
); 


CREATE USER idm IDENTIFIED BY novell; 


NOTE: Examples used throughout the implementation guide are for the Oracle database. 


A logical table. When queried via a SELECT statement, the view is constituted by executing the 
SQL query supplied when the view was defined. Views are a useful abstraction mechanism for 
representing multiple tables of arbitrary structure as a single table. 


CREATE VIEW view_usr 
( 


pk_idu, 
fname, 
lname 
) 
AS 
SELECT idu, fname, lname from usr; 


Identity Columns/Sequences 


Identity columns and sequences are used to generate unique primary key values. 


An identity column is a self-incrementing column used to uniquely identify a row in a table. 
Identity columns values are automatically filled in when a row is inserted into a table. 


A sequence object is a counter that can be used to uniquely identify a row in a table. Unlike an 
identity column, a sequence object is not bound to a single table. However, if it is used by a single 
table, a sequence object can be used to achieve an equivalent result. 


The following is an example of a sequence object: 


CREATE SEQUENCE seq_idu 
START WITH 1 

INCREMENT BY 1 
NOMINVALU! 
N 
O 


OMAXVALUE 
RDER; 
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Transaction 


A transaction is an atomic database operation that consists of one or more statements. When a 
transaction is complete, all statements in the transaction are committed. When a transaction is 
interrupted or one of the statements in the transaction has an error, the transaction is said to roll 
back. When a transaction is rolled back, the database is left in the same state 1t was before the 
transaction began. 


Transactions are either manual (user-defined) or automatic. Manual transactions can consist of one 
or more statements and must be explicitly committed. Automatic transactions consist of a single 
statement and are implicitly committed after each statement is executed. 


Manual (User-Defined) Transactions 


Manual transactions usually contain more than one statement. DDL statements typically cannot be 
grouped with DML statements in a manual transaction. The following example shows a manual 
transaction: 


SET AUTOCOMMIT OFF 

INSERT INTO usr(lname) VALUES (’Doe’); 

UPDATE usr SET fname = “John” WHERE idu = 1; 
COMMIT; -- explicit commit 


Automatic Transactions 


Automatic transactions consist of only one statement. They are often referred to as auto-committed 
statements because changes are implicitly committed after each statement. When a statement runs 
automatically, it is autonomous of any other statement. The following example shows an 
automatic transaction: 


SET AUTOCOMMIT ON 
INSERT INTO emp(lname) VALU 
-- implicit commit 


El 


S(’Doe’); 


Stored Procedures or Functions 


A stored procedure or function is programmatic logic stored in a database. They can be invoked 
from almost any context. 


The Subscriber can use stored procedures or functions to retrieve primary key values from rows 
inserted into tables for the purpose of creating associations. Stored procedures or functions can 
also be invoked from within embedded SQL statements or triggers. 


The distinction between stored procedures and functions varies by database. Typically, both can 
return output, but they differ in how they do it. Stored procedures usually return values through 
parameters. Functions usually return values through a scalar return value or result set. 


The following is an example of a stored procedure definition that returns the next value of a 
sequence object: 


CREATE SEQUENCE seq_idu 
TART WITH 1 

R 

I 


EMENT BY 1 
NVALU 


Fy 
Fy 
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CREATE 
PROCEDURE sp idu(io idu IN OUT INTEGER) 


IS 
BEGIN 
IF (io idu IS NULL) THEN 
SELECT seq idu.nextval INTO io idu FROM DUAL; 
END IF; 


END sp idu; 


Trigger 

A database trigger is programmatic logic associated with a table, which fires or executes under 
certain conditions. Triggers are often useful for creating side effects in a database. In the context 
of this driver, triggers are useful for publication event capture. The following is an example of a 
database trigger on the usr table. 
CREATE TABLE usr 
( 

idu INTEGER, 

fname VARCHAR2 (64), 

lname VARCHAR2 (64) 
y; 

t = trigger; i = insert 

CREATE TRIGGER t_usr_i 

AFTER INSERT ON usr 

FOR EACH ROW 
BEGIN 

UPDATE usr SET fname = ’John’; 
END; 
When a statement is executed against a table with triggers, a trigger fires if the statement satisfies 
the conditions specified in the trigger. For example, using the above table, suppose the following 
insert statement is executed: 
INSERT INTO usr(lname) VALUES (’ Doe’ ) 
Trigger t emp i fires after the insert statement is executed and the following update statement 
is also executed: 
UPDATE usr SET fname = “John” 
A trigger can typically be fired before or after the statement that triggered it. Statements that are 
executed as part of a database trigger are typically included in the same transaction as the 
triggering statement. In the above example, both the INSERT and UPDATE statements would be 
committed or rolled back together. 

Instead-Of-Trigger 


An instead-of-trigger is programmatic logic associated with a view, which fires or executes under 
certain conditions. Instead-of-triggers are useful for making views writable/subscribeable. They 
are often used to define what it means to INSERT, UPDATE, and DELETE from a view. The 
following is an example of an instead-of-trigger on the usr table. 


CREATE TABLE usr 
( 


idu INTEGER, 
fname VARCHAR2 (64), 
lname VARCHAR2 (64) 
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CREATE VIEW view usr 


pk idu, 
fname, 
lname 


SELECT idu, fname, lname from usr; 


t = trigger; i = insert 
CREATE TRIGGER t view usr i 
INSTEAD OF INSERT ON usr 


BEGIN 
INSERT INTO usr(idu, fname, lname) 
VALUES (:NEW.pk idu, :NEW.fname, :NEW.lname); 


When a statement is executed against a view with instead-of-triggers, an instead-of-trigger fires if 
the statement satisfies the conditions specified in the trigger. Unlike triggers, instead-of-triggers 
always fire before the triggering statement. Also, unlike regular triggers, instead-of-triggers are 
executed instead of, not in addition to, the triggering statement. 


For example, using the above view, suppose the following insert statement is executed: 


INSERT INTO view usr(pk idu, fname, lname) 
VALUES (1, ‘John’, ‘Doe’) 


Instead-of-trigger t view usr i would fire and execute the following statement: 


INSERT INTO usr(idu, fname, lname) 
VALUES (:NEW.pk idu, :NEW.fname, :NEW.lname); 


instead of the original insert statement. In this example, the statements happen to be equivalent. 


Data Synchronization Models 
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The driver supports two data synchronization models: direct and indirect. Both terms are best 
understood with respect to the final destination of the data being synchronized. 


Direct synchronization is usually associated with views because views provide the abstraction 
mechanism that best facilitates integration with existing customer tables. 


Indirect synchronization is usually associated with tables because customer tables likely don't 
match the structure required by the driver, so they can only serve as an intermediate staging area. 
Although it is possible that the structures might match, it is highly unlikely. 


This means that for all practical purposes direct synchronization = view, indirect synchronization 
= table. 


The following sections describe how direct and indirect synchronization work on both the 
Subscriber and Publisher channels. 
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Indirect Synchronization 


Indirect synchronization uses intermediate staging tables to synchronize data between Identity 
Manager and a database. 


The following diagrams explains how indirect synchronization works on the Subscriber and 
Publisher channels. In the following scenarios, you can have one or more customer tables and 
intermediate staging tables. 


Subscriber Channel 


Indirect Synchronization 
on the Subscriber Channel 


Database 


The Subscriber updates the intermediate staging tables in the synchronization schema. The 
synchronization triggers then update customer tables elsewhere in the database. 


Publisher Channel 


Indirect Synchronization 
on the Publisher Channel 


Database 


When customer tables are updated, synchronization triggers update the intermediate staging 
tables. Publication triggers then insert one or more rows into the event log table. The Publisher 
then reads the inserted rows and updates the Identity Vault. 
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Depending on the contents of the rows read from the event log table, the publisher might need to 
retrieve additional information from the intermediate tables before updating the Identity Vault. 
After updating the Identity Vault, the Publisher then deletes or marks the rows as processed. 


Direct Synchronization 


Direct synchronization typically uses views to synchronize data between Identity Manager and a 
database. Tables can be used if they conform to the structure required by the driver. 


The following diagrams explain how direct synchronization works on the Subscriber and Publisher 
channels. In the following scenarios, you can have one or more customer tables or views. 


Subscriber Channel 


Direct Synchronization on 
the Subscriber Channel 


Database 


Synchronization 
Schema 


(Gubserber } = 


The Subscriber updates existing customer tables through a view in the synchronization schema. 


NOTE: Direct synchronization without a view is only possible if customer tables match the structure required 
by the driver. For additional information, refer to "Indirect Synchronization” on page 67. 


Publisher Channel 


Direct Synchronization on 
the Publisher Channel 


Database 


Synchronization 
Schema 
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When a customer table is updated, publication triggers insert rows into the event log table. The 
Publisher then reads the inserted rows and updates the Identity Vault. 


Depending on the contents of the rows read from the event log table, the publisher might need to 
retrieve additional information from the view before updating the Identity Vault. After updating 
the Identity Vault, the Publisher then deletes or marks the rows as processed. 


Triggerless Publication 


Triggers are no longer required to log publication events. In situations where triggers cannot be 
used for granular event capture, the Publisher can derive database changes by inspecting database 
data. Triggerless publication is particularly useful when support contracts forbid the use of triggers 
on database application tables or for rapid prototyping. 


Triggerless vs. Triggered Publication 


Triggerless publication is less efficient than triggered publication. With triggered publication, 
what changed is already known. With triggerless publication, change calculation must occur 
before events can be processed. 


Triggerless publication, unlike triggered publication, does not preserve event order. It only 
guarantees that by the end of a polling cycle, objects in the database and the Identity Vault will be 
in sync. 


Triggerless publication, unlike triggered publication, does not provide historical data such as old 
values. It can only provides information on the current state of an object, not the previous state. 


Triggerless publication does have the advantage of being much simpler because it reduces 
database-side dependencies. Writing database triggers can be complicated and requires extensive 
knowledge of database-specific SQL syntaxes. 


Direct Triggerless Publication 


Direct Synchronization on 
the Publisher Channel 
without Triggers 
Database 


Synchronization 
Schema 
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Indirect Triggerless Publication 


Indirect Synchronization 
on the Publisher Channel 
without Triggers 

Database 


dial 
ARA le 


Synchronization 
Schema 


(TT 


Intermediate 
Tables(s 
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Understanding Driver Prerequisites 


The following sections contain important information you should review before installing and 
configuring the driver. 


+ "Driver Prerequisites” on page 23 

+ "Supported Platforms” on page 23 

+ "Supported Databases” on page 23 

+ "Supported Third-Party JDBC Drivers” on page 23 
+ “Known Issues” on page 23 


+ “Limitations” on page 24 


Driver Prerequisites 


The DirXML? Driver for JDBC requires the following: 
U Novell Nsure™ Identity Manager 2 
Q) Java Virtual Machine (JVM*) 1.4 or higher 
Q) A supported third-party JDBC driver 


Supported Platforms 


The driver runs on all Identity Manager-enabled platforms, including Windows* NT*/2000, 
NetWare®, Solaris", Linux”, and ATX. 


Supported Databases 


Refer to "Database Interoperability” on page 111. 


Supported Third-Party JDBC Drivers 


Known Issues 


Refer to “Third-Party JDBC Driver Interoperability” on page 97. 


+ eDirectory™ Time and Timestamp syntaxes are inadequate for expressing the range and 
granularity of their database counterparts. 


This is a publication problem because database time-related types typically have a wider range 


and greater degree of granularity (typically nanoseconds). The converse is not true. Refer to 
“Time syntax” on page 39 for more information. 
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Limitations 


+ This product is unable to parse proprietary database time stamp formats. 


Some databases, such as Sybase and DB2, have proprietary time stamp formats that cannot be 
parsed by the java.sql.Timestamp (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 
Timestamp.html) class. 


When synchronizing time stamp columns from these databases, by default this product 
assumes time stamp values placed in the event log table are in ODBC canonical format (that 
is, yyyy-mm-dd hh:mm:ss.fffffffff). 


The recommended method for enabling this product to handle proprietary database time 
stamp formats is to implement a custom DBTimestampTranslator class. This interface is 
documented in the javadocs that ship with this product. Using this approach avoids the 
problem ofreformatting time stamps in the database before they are inserted into the event log 
table or reformatted them in style sheets. This product ships with default implementations for 
the native DB2 time stamp format and the Sybase style 109 time stamp format. 


Statements executed against the database server might block indefinitely. 


Blocking can be caused by a myriad of factors. To mitigate the likelihood of blocking, we 
recommend that you do not set the parameter “Transaction isolation level” on page 46 to a 
level greater than read committed. 


Typically, blocking is caused by a database resource being exclusively locked. Because the 
locking mechanisms and locking SQL vary by database, the general solution to this problem 
1s to implement a custom DBLockStatementGenerator class. For additional information, 
see “Lock statement generator class” on page 48. This product ships with a default 
implementation for Oracle. 


The JDBC interface defines a method that allows a statement to timeout after a specified 
number of seconds, signature java.sql.Statement.setQueryTimeout(int):void (http:// 
java.sun.com/j2se/1.5.0/docs/api/java/sql/Statement.html). Unfortunately, implementations 
of this method between third-party JDBC drivers vary from unimplemented to buggy. For this 
reason, use of this method was deemed unsuitable as a general-purpose solution. 


The driver does not support the use of delimited (quoted) database identifiers. 


JDBC 2 data types are not supported with the exception of Large Object data types (LOBs) 
such as CLOB and BLOB. 


JDBC 3 data types are not supported. 


PostgreSQL does not support <check-object-password> events. Authentication is 
controlled by manually inserting entries into the pg_hba.conf file. 
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Installing or Upgrading the IDM Driver for JDBC 


In this section, you will find information and procedures to help you install and upgrade this 
product: 


+ “Installing” on page 25 
+ “Upgrading” on page 32 
+ “Activating” on page 32 


For uninstallation information, refer to Chapter 9, “Uninstalling the IDM Driver for JDBC,” on 
page 125 


IMPORTANT: We recommend installing or uninstalling driver configurations and database scripts as a unit. 
To prevent unintentional mismatching, database scripts and driver configurations contain headers with a 
version number, the target database name, and the database version. 


Installing 


The Identity Manager Driver for JDBC requires Identity Manager and database-side configuration. 
Identity Manager-side configuration consists of importing a driver configuration file. Database- 
side configuration consists of executing SQL scripts. We recommend that you execute database 
SQL scripts and test them before starting the driver. 


The shipping configuration is a sample only. We recommend that you install the shipping 
configuration into a test environment before attempting customization. 


Identity Manager-Side Installation 
+ “Installing the IDM Driver for JDBC” on page 25 
+ “Importing the Sample Driver Configuration File” on page 26 


Installing the IDM Driver for JDBC 


You should use these instructions if no previous installation exists for the driver. After you have 
downloaded the stand-alone installer, complete the following instructions to install this product: 


1 Run the installer. 


2 Copy the appropriate third-party JDBC driver files into the following directory by platform: 


Platform Directory Path 
NetWare® sys:\system\lib 
Solaris, Linux, or AIX lusr/lib/dirxml/classes 
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Platform Directory Path 


Windows NT/2000 Novell\NDS\lib 


Refer to “Supported Third-Party JDBC Drivers” on page 98 for info on third-party JDBC 
driver filenames and where to download them. 


3 Restart eDirectory. 


4 Start iManager. 


Importing the Sample Driver Configuration File 
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The JDBCv2.xm1 configuration file creates and configures the Identity Manager objects needed 
in order for the sample driver to work properly. It also includes sample policies you can customize 
to suit your needs. 


1 In iManager, select DirXML Management > Create Driver. 
2 Select a driver set. 


If you place this driver in a new driver set, you must specify a driver set name, context, and 
associated server. 


3 Mark Import a Driver Configuration from the Server and select the JDBCv2 . xml file. 


The driver configuration file is installed on the Web server when you set up iManager. 


4 You will be prompted to enter a name for the driver. Specify the driver’s name, then click 
Next to continue. 


5 (Optional) Click Define Security Equivalences. 


5a Click Add, then select an object with Admin rights (or any other rights that you want the 
driver to have). 


5b Click Apply, then click OK. 

6 (Optional) Click Exclude Administrative Roles to exclude objects from replication. 
6a Click Add, then select any users you want to exclude (such as the admin user). 
6b Click Apply, then click OK. 


7 Click Next to view the import summary. Verify that the configuration is correct, then click 
Finish with Overview. 


The necessary Identity Manager driver objects have now been created. If you didn’t define security 
equivalences or exclude administrative users at import time, you can complete these tasks by 
modifying the driver object's properties. 


Configuration File Conventions 


+ Database usernames are the Surname of a User concatenated with the corresponding numeric 
primary key value (for example, John Doe’s username could be Doel). 


+ Initial passwords are the Surname of a User (for example, John Doe’s password would be 
Doe). 


Sybase* passwords must be at least 6 characters long. When shorter than 6 characters, last 
names are padded with the character ‘p’ (for example, John Doe’s password would be 
Doeppp). The padding character can be adjusted in the Subscriber Command Transformation 
policies. 
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Database-Side Installation 


The following information explains how to install and configure database objects (tables, triggers, 
indexes, and so forth) for synchronization with the sample driver configuration. 


SQL scripts are located in the install-dir\jdbc\sql\abbreviated-database-name directory. 
+ “IBM DB2 Universal Database (UDB) Installation” on page 28 


+ “Informix Dynamic Server (IDS) Installation” on page 29 


+ “Microsoft SQL Server Installation” on page 29 


+ “MySQL Installation” on page 30 
+ “Oracle Installation” on page 30 


+ “PostgreSQL Installation” on page 30 


+ “Sybase Adaptive Server Enterprise (ASE) Installation” on page 31 


SQL Script Conventions 


All SQL scripts use the same conventions, regardless of database. 


The maximum size of a DB2 identifier is 18 characters. This least common denominator length 
defines the upper bound of database identifier length across all SQL scripts. Due to this length 
restriction, abbreviations are used. The following table summarizes identifier abbreviations and 


their meaning: 


Abbreviation 


proc_! 


idx_ 


Interpretation 


stored procedure/function 


index 

trigger 

on insert trigger 

on update trigger 

on delete trigger 

check constraint 

view primary key constraint 
view foreign key constraint 
view multi-valued column 


view single-valued column (implicit default) 


I The more common abbreviation is sp_. This prefix is reserved for system stored procedures on 
Microsoft SQL Server and forces lookup of a procedure first in the master database before 
evaluating any qualifiers (for example, database, owner, etc.). In order to maximize procedure 
lookup efficiency, this prefix has been deliberately avoided. 
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The following table identifies identifier naming conventions for indexes, triggers, stored 
procedures, functions, and constraints: 


Database Object 

stored procedure/function 
index 

trigger 

primary key constraint 
foreign key constraint 


check constraint 


Naming Convention Examples 

proc procedure-or-function-name proc_idu 
idx_unqualified-table-name_sequence-number idx_indirectlog_1 
tgr_unqualified-table-name_triggering-statement-type_sequence-number tgr_usr_i_1 
pk_unqualified-table-name_column-name pk_usr_idu 
fk_unqualified-table-name_column-name fk_usr_idu 
chk_unqualified-table-name_column-name chk_usr_idu 


Other conventions include: 


+ 


All database identifiers are lowercase. This is the most commonly used case convention 
between databases. 


String field lengths are 64 characters. Fields of this length can hold most eDirectory attribute 
values. You might want to refine field lengths to enhance storage efficiency. 


For performance reasons, primary key columns use native, scalar numeric types whenever 
possible (such as BIGINT as opposed to NUMERIC). 


The record id column in event log tables has the maximum numeric precision permitted 
by each database to avoid overflow. 


Identity columns and sequence objects do not cache values. Some databases throw away 
cached values when a rollback occurs, which can cause large gaps in identity column or 
sequence values. 


IBM DB2 Universal Database (UDB) Installation 


IMPORTANT: For IBM* DB2, you must manually create operating system user accounts before running the 
provided SQL scripts. 


Because the process of creating user accounts differs between operating systems, Step 1 below is OS- 
specific. These instructions are for a Windows NT operating environment. If you rerun the SQL scripts, you 
should only repeat steps 2 through 5. 


The directory context for DB2 is install-dir\jdbc\sql\db2_udb\install. 


1 


Create user accounts for users idm, indirect and direct using novell as the password 
in User Manager for Domains. 


* Remember to deselect the User Must Change Password at Next Login check box for this 
account. 


+ You might want to also select the Password Never Expires check box. 


NOTE: The remaining instructions are OS-independent. 


2 Copy idm db2.jar to your DB2 server. 


3 Change the name of the administrator account name and password and adjust the path to 


idm_db2. jar in the installation scripts. 
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4 Execute the 1 install.sgql script from the Command Line Processor (CLP.) 
For example: 
db2 -f 1 install.sql 


IMPORTANT: The scripts won't execute in the Command Center interface beyond version 7. The scripts 
utilize the “Y line continuation character, which later versions of the Command Center don't recognize. 


5 For versions 8 or later, execute the 2 install 8.sq1 script. 


For example: 
db2 -f 2 install 8.sql 


Informix Dynamic Server (IDS) Installation 


IMPORTANT: For Informix Dynamic Server, you must manually create an operating system user account 
before running the provided SQL scripts. 


Because the process of creating user accounts differs between operating systems, Step 1 below is OS- 
specific. These instructions are for a Windows NT operating environment. If you rerun the SQL scripts, you 
should only repeat steps 2 through 4. 


The directory context for Informix SQL scripts is install-dir\jdbc\sql\informix_ids\install. 


1 In Windows NT, create a user account for user idm using nove11 as the password in User 
Manager for Domains. 


+ Remember to deselect the User Must Change Password at Next Login check box for this 
account. 


+ You might want to also select the Password Never Expires check box. 
NOTE: The remaining instructions are OS-independent. 
2 Start a client such as SQL Editor. 


3 Log in to your server as the informix user or another user with DBA (database 
administrator) privileges. By default, the password for informix is informix. 


NOTE: If you execute scripts as a user other than informix, you must change all references to informix in 
the scripts prior to execution. 


4 Open and execute 1 install.sql from either the ansi (transactional, ANSI-compliant), 
log (transactional, non-ANSI-compliant), no log (non-transactional, non-ANSI- 
compliant) subdirectories depending upon which type of database you want to create. 


Microsoft SQL Server Installation 


The directory context for Microsoft” SQL Server scripts is install-dir\jdbc\sql\mssql\install. 
1 Start a client such as Query Analyzer. 
2 Log in to your database server as the sa user. By default, the sa user has no password. 


3 Execute the installation script. For version 7, execute 1 install 7.sgq1. For version 8 
(2000), execute 1_install_2k.sql. 


NOTE: The execute hotkey in Query Analyzer is F5. 
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MySQL Installation 


The directory context for MySQL* SQL scripts is install-dir\jdbc\sql\mysql\install. 

1 From a MySQL client, such as mysql, log in as root user or another user with administrative 
privileges. By default, the root user has no password. For example, from the command line, 
execute: 
mysql -u root -p 


2 Execute the installation script 1 install innodb.sqlorl install myisam.sql 
depending upon which table type you whish to use. For example: 


mysql> X. c:11_install_innodb.sql 


TIP: Don't use a semi-colon to terminate this statement. 


Oracle Installation 


The directory context for Oracle” SQL scripts is install-dir\jdbc\sql\oracle\install. 


1 From an Oracle client, such as SQL Plus, log in as the SYSTEM user. By default, the password 
for SYSTEM is MANAGER. 


NOTE: |f you execute scripts as a user other than SYSTEM with password MANAGER, you must change 
all references to SYSTEM in the scripts prior to execution. 


2 Execute the installation script 1_instal1. sql. For example: 


SQL> @c:\l_install.sql 


PostgreSQL Installation 


The directory context for PostgreSQL scripts is install-dir\jdbc\sql\postgres\install. The directory 
context for executing Postgres commands is postgres-install-dir/pgsql/bin. 


1 Create the database idm. For example, from the UNIX command line, execute the command 
createdb: 


./createdb idm 

2 Install the plpgsql procedural language to database idm. For example, from the UNIX 
command line, execute the command createlang: 
./createlang plpgsql idm 

3 From a Postgres client such as psql, logon as user postgres to the idm database. By default, 
the postgres user has no password. For example, from the UNIX command line, execute 
the command psa]: 
./psql -d idm postgres 


4 From inside psql, execute the script 1_install.sql. For example: 


idm=# Xi 1 install.sql 


5 Update the pg hba.conf file. For example, add entries for the i dm database user adjusting 
the IP-ADDRESS and IP-MASK as necessary: 


# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD 
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# allow driver user idm to connect to database idm 
host idm idm 255.255+255:255 255,255:255.:0 password 


6 Restart the Postgres server to effect changes made to the pg hba.conf file. 


Sybase Adaptive Server Enterprise (ASE) Installation 


IMPORTANT: Ensure that you have JDBC metadata support installed on the database server. This is usually 
only an issue for versions prior to 12.5. 


The directory context for Sybase SQL scripts is install-dir\jdbc\sql\sybase_ase\install. 


1 From a Sybase client, such as isql, log in as the sa user and execute the 1_install.sql 
installation script. By default, the sa account has no password. For example, from the 
command line, execute: 


isql -U sa -P -i 1 install.sql 


Testing 
There are test scripts for each database which are located in the following directories, by database: 
Database Test SQL Scripts Location 
IBM DB2 Universal Database install-dir\jdbc\sql\db2_udb\test 
Informix Dynamic Server install-dir\jdbc\sql\informix_ids\log\test 
install-dir\jdbc\sql\informix_ids\no_log\test 
Informix ANSI test scripts are located in the log\test 
subdirectory. 
Microsoft SQL Server install-dirydbeisqlimssqlitest 
MySQL install-dirjdbelsqlimysqlitest 
Oracle install-dir\j\dbc\sql\oracle\test 
PostgreSQL install-dir\jdbc\sql\postgres\test 
Sybase Adaptive Server Enterprise _jnstall-dir\jdbc\sql\sybase_ase\test 
We recommend that you try the test scripts before starting the sample driver. 
Troubleshooting 


+ Publication events might not be recognized by the publisher unless you explicitly commit 
changes. For the commit keywords of supported database, see “Commit Keywords” on 
page 115. 


+ The test scripts should be executed by a user other than the driver’s idm database user 
account. If you execute them as the idm user, events are ignored by the driver’s Publisher 
channel unless publication loopback is allowed. For additional information on allowing or 
disallowing publication loopback, refer to parameter “Allow loopback?” on page 62. 
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Upgrading 


Use the following information and procedures if you are upgrading the driver from a previous 
version. 


Upgrading from Versions Earlier than 1.5 


For versions prior to 1.5, you must upgrade to version 1.5 first. Please refer to the DirXML Driver 
1.5 for JDBC Implementation Guide (http://www.novell.com/documentation/lg/dirxmldrivers/ 
index.html). Be sure to use the 2.0 association utility. It supersedes all previous versions. 


Upgrading from 1.5 or Later to 2.0 


After you download the 2.0 driver, run the standalone installer. 


Backward Incompatibilities 


+ The driver now requires a minimum of two database connections for bi-directional 
synchronization. For additional information, refer to parameter “Use minimal number of 
connections?” on page 42. 


+ The driver now returns schema qualifiers (when available) for logical database class names 
(that is, parent table or view names). This change will not affect existing configurations unless 
class names are re-mapped in Schema Mapping policies, in which case, all references to class 
names in existing policy will need to be schema-qualified. 


+ Configurations that reference the 
com.novell.nds.dirxml.driver.jdbc.util.MappingPolicy class will need to 
be slightly adjusted. Methods in this class no longer edit the source document. Instead, they 
return node sets that must be copied into the destination document. Examples of how to do 
this are included in the sample driver configuration file JDBCv2 . xml. 


+ Configurations deployed against DB2/AS400 or other legacy databases that do not have a 
notion of column position will need to be slightly altered. You'll need to explicitly add and 
set parameter “Sort column names by” on page 51 to sort column names by string collation 
order. The default behavior has been changed to sort column names by hexadecimal value. 


Activating 


Activation must be completed within 90 days of installation or the driver will not run. 


For activation information, refer to Activating Novell Identity Management Products (http:// 
www.novell.com/documentation/lg/dirxm120/admin/data/afbx4oc.html). 
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Configuring the IDM Driver for JDBC 


This section explains how to configure this product. 
+ "Smart Configuration” on page 33 
+ “Deprecated Parameters” on page 36 
+ “Authentication Parameters” on page 36 
+ “Driver Parameters” on page 37 
+ “Subscription Parameters” on page 52 
+ “Publication Parameters” on page 59 
+ “Trace Levels” on page 65 


+ "Configuring Third-Party JDBC Drivers” on page 65 


Smart Configuration 


This product is capable of recognizing the supported set of third-party JDBC drivers and databases 
and dynamically configuring the majority of driver compatibility parameters automatically. This 
alleviates the need for the end user to understand and explicitly set them. This feature is 
implemented via XML descriptor files that describe a third-party JDBC driver or database to this 
product. 


Descriptor Types 

There are four types of descriptor files: 
1. Third-party JDBC driver 
2. Third-party JDBC driver import 
3. Database 


4. Database import 


Reserved Names 


Descriptor files that ship with this product begin with the underscore character ( ). Any descriptor 
filenames beginning with the underscore character are reserved to ensure that descriptor files that 
ship with this product do not conflict with custom descriptor files. Because of this, custom 
descriptor files must not begin with the underscore character. 


Import Descriptors 


Descriptor import files allow content to be shared by multiple, non-import descriptor files, thereby 
reducing their size, minimizing the need for repetition of content and increasing maintainability. 
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Import files cannot be imported across major types. That is, JDBC driver descriptors cannot import 
database imports and database descriptors cannot import JDBC driver imports. 


Furthermore, custom non-import descriptors cannot import reserved descriptor imports. For 
example, if a custom third-party JDBC driver descriptor file named custom.xml tries to import a 
reserved third-party JDBC driver descriptor named reserved.xml, an error will be issued. The 
reason for this is to ensure that there are no dependencies between reserved and custom import files 
so as to allow extension of existing reserved descriptor files in later versions of this product. 


Descriptor File Locations 


Descriptor files must be located in a jar file whose name begins with the prefix “jdbc” (case- 
insensitive) that resides in the runtime classpath. 


The following table identifies where descriptors should be placed within a descriptor jar file: 


Descriptor Type Directory Path 

Third-party JDBC driver com/novell/nds/dirxml/driver/jdbc/db/descriptor/driver 
Third-party JDBC driver import com/novell/nds/dirxml/driver/jdbc/db/descriptor/driver/import 
Database com/novell/nds/dirxml/driver/jdbc/db/descriptor/db 
Database import com/novell/nds/dirxml/driver/jdbc/db/descriptor/db/import 


Reserved descriptor files are located in the JDBCConfig. jar file. Custom descriptors should be 
placed in a different jar file to ensure that they are not overwritten when this product is updated. 


Precedence 


Parameters explicitly specified through a management console, such as iManager, always have 
precedence over those specified through descriptor files. Descriptor file parameters only take 
effect when a parameter is not set through the management console. 


Parameters and other information specified in a non-importable descriptor file always have 
precedence over that specified in descriptor import files. If a parameter or other information is 
duplicated within a descriptor file, the first instance of the parameter or information takes 
precedence over subsequent instances. 


Between import files, precedence is determined by import order. That is, import files declared 
earlier in the import list take precedence over those that follow. 
Custom Descriptor Best Practices 

U Custom descriptor files name should not being with the underscore ( _ ) character. 


0 Custom descriptor files should be located in a jar file other than JDBCConfig. jar, and the 
filename should begin with the prefix “jdbc” (case-insensitive). 


U Custom descriptors should not import reserved import files (that is, those beginning with the 
underscore character). 
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Descriptor File DTDs 


To aid you in constructing custom descriptor files, the DTDs for all descriptor file types have been 
provided in the appendixes as detailed in the following table: 


Descriptor Type Appendix 


Third-party JDBC driver Appendix F, “Third-Party JDBC Driver Descriptor DTD,” on page 145 


Third-party JDBC driver Appendix G, “Third-Party JDBC Driver Descriptor Import DTD,” on 


import page 147 
Database Appendix H, “Database Descriptor DTD,” on page 149 
Database import Appendix I, “Database Descriptor Import DTD,” on page 151 


Configuration Parameters 


Configuration parameters are divided into the following major and minor categories: 
+ “Authentication Parameters” on page 36 
¢ “Driver Parameters” on page 37 
+ “Uncategorized Parameters” on page 38 
+ “Database Scoping Parameters” on page 40 
+ “Connectivity Parameters” on page 42 
+ “Compatibility Parameters” on page 44 
+ “Subscription Parameters” on page 52 
+ “Uncategorized Parameters” on page 52 
+ “Primary Key Parameters” on page 54 
+ “Publication Parameters” on page 59 
+ “Uncategorized Parameters” on page 59 
+ “Triggered Publication Parameters” on page 61 
¢ “Triggerless Publication Parameters” on page 62 


+ “Polling Parameters” on page 63 


Setting Driver Parameters 
1 In iManager, click DirXML Management > Overview. 
2 Locate the driver set containing the driver, then click the driver’s icon. 


3 From the Driver Overview, click the driver object, which will display the driver’s 
configuration parameters. 
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Deprecated Parameters 


The following parameters have been deprecated since version 1.6: 


Tag Name Justification 


connection-tester-classí The driver now dynamically creates a connection tester class at runtime 
based upon information in XML descriptor files. 


connection-test-stmt! The driver now dynamically creates a connection tester class at runtime 
based upon information in XML descriptor files. 


reconnect-interval The reconnect interval is now fixed at 30 seconds on both channels. 


! These parameters are still operable to ensure backwards compatibility. Their continued use, 
however, is discouraged. 


Authentication Parameters 


After you import the driver, you need to provide authentication information for the target database. 
There are three authentication-related parameters: 

+ “Authentication ID” on page 36 

+ “Authentication Context” on page 36 


+ “Application Password” on page 37 


Authentication ID 


Authentication ID is the name of the driver’s database user/login account. The database privileges 
required for this account to authenticate to a supported database are detailed in each database’s 
installation SQL scripts located in the install-dir\tools\sql\abbreviated-database-name\install 
directory. 


The default value for the sample configuration is idm. 


Authentication Context 
The authentication context is the JDBC URL of the target database. 


URL format and content are proprietary and differ between third-party JDBC drivers. There are 
some similarities in content, however. Each URL, whatever the format, usually includes an IP 
address or DNS name, port number, and a database identifier. Consult your third-party driver 
documentation for the exact syntax and the content requirements of your driver. 


For a list of JOBC URL syntaxes for supported third-party drivers, see “JDBC URL Syntaxes” on 
page 99. 


IMPORTANT: Changing anything in this value other than URL properties will force a resync of all objects 
when triggerless publication is used. 
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Application Password 


Application password is the password for the driver’s database user/login account. The default 
value for the sample driver configuration is novell. 


Driver Parameters 


The following table is a summary of all driver-level parameters and their properties: 


Display Name Tag Name Sample Value Default Value Required 
Third-party JDBC driver jdbc-class oracle.jdbc.driver.OracleDriver (none) yes 
class name 
Schema name sync-schema indirect (none) yes! 
Table/view name(s) sync-tables usr (none) yes! 
Include filter expression include-table-filter IDM_.* (none) no 
Exclude filter expression exclude-table-filter BIN\$.{22}==\$0 (none) no 
Connection initialization connection-init USE idm (none) no 
statements 
Time syntax time-syntax 1 (integer) 1 (integer) no 
State directory state-dir . (current directory) . (current directory) no 
JDBC driver descriptor jdbc-driver-descriptor ora_client_thin.xml (none) no 
filename 
Database descriptor database-descriptor ora_10g.xml (none) no 
filename 
Use manual transactions? use-manual-transactions 1 (yes) (dynamic?) no 
Transaction isolation level transaction-isolation-level read committed (dynamic?) no 
Reuse statements? reuse-statements 1 (reuse) (dynamic?) no 
Number of returned result handle-stmt-results one (dynamic?) no 
sets 
Enable statement-level enable-locking 1 (yes) 0 (no) no 
locking? 
Lock statement generator lock-generator-class com.novell.nds.dirxml.driver.jdbc (dynamic?) no 
class .db.lock.OraLockGenerator 
Enable referential attribute enable-refs 1 (yes) 1 (yes) no 
support? 
Force username case force-username-case upper (to upper case) (none) no 
Left outer-join operator left-outer-join-operator (+) (dynamic?) no 
Retrieve minimal metadata? minimal-metadata 0 (no) (dynamic?) no 
Use minimal number of use-single-connection 0 (no) (dynamic?) no 
connections? 
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Display Name Tag Name Sample Value Default Value Required 


Function return method function-return-method result set (dynamic?) no 


Supports schemas in supports-schemas-in- 1 (yes) (dynamic?) no 
metadata retrieval? metadata-retrieval 
Sort column names by column-position-comparator com.novell.nds.dirxml.driver.jdbc (dynamic?) no 


.util.config.comp.StringByteCom 
parator (hexadecimal value) 


' These parameters are mutually exclusive. 
? This default is derived dynamically at runtime from descriptor files and database metadata. 
3 These defaults are derived dynamically at runtime from descriptor files. 


Driver parameters fall into three major subcategories: 
+ “Uncategorized Parameters” on page 38 
+ “Database Scoping Parameters” on page 40 
+ “Connectivity Parameters” on page 42 


+ “Compatibility Parameters” on page 44 


Uncategorized Parameters 


This section describes the following driver parameters: 
+ “Third-party JDBC driver class name” on page 38 
+ “Time syntax” on page 39 


+ “State directory” on page 39 


Third-party JDBC driver class name 
This parameter is the fully-qualified Java class name of your third-party JDBC driver. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name jdbc-class 

Required? yes 

Case-Sensitive? yes 

Sample Value oracle.jdbc.driver.OracleDriver 
Default Value (none) 


For a list of supported third-party JDBC driver classnames, see “JDBC Driver Class Names” on 
page 99. 
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Time syntax 


State directory 


This parameter specifies the format of time-related data types returned by this product. There are 
two options: 


1. Return database Time, Date, and Timestamp values as 32-bit signed integers and map them 
to eDirectory attributes of type Time or Timestamp. This is the default. 


2. Return database Time, Date, and Timestamp values as canonical strings and map them to 
attributes of type Numeric String. 


The first option has two problems. First, eDirectory Time and Timestamp syntaxes cannot express 
as large a date range as database Date or Timestamp syntaxes (approximately 136 years). Second, 
eDirectory Time and Timestamp syntaxes are granular to the second. Database Timestamp 
syntaxes are often granular to the nanosecond. 


The second option overcomes these limitations. The following table shows abstract database data 
types and their corresponding canonical string representations: 


JDBC Data Type Canonical String Format: 
java.sql.Time HHMMSS 

java.sql.Date CCYYMMDD 

java.sql.Timestamp CCYYMMDDHHMMSSNNNNNNNNN 


LGE century, Y = year, D = day, H = hour, M = minute, S = second, N = nano 


These fixed-length formats have the virtue of collating in chronological order on any platform in 
any locale. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name time-syntax 

Required? no 

Default Value 1 (integer) 

Legal Values 1 (integer) 
2 (string) 


This parameter specifies where a driver instance should store state data. State data is currently used 
for triggerless publication although it maybe used to store additional state information in the 
future. 


There are two state files per driver instance. State filenames follow the format jdbc_driver- 
instance-guid.db and jdbc_driver-instance-guid.lg. For example, jdbc_bd2a3dd5-d571-4171- 
a195-28869577b87e.db and jdbc_bd2a3dd5-d571-4171-a195-28869577b87e.lg are state 
filenames. If you need to manually identify and delete a driver instance’s state files, each driver 
instance’s GUID is traced on startup. Defunct state files (those belonging to deleted drivers) in the 
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current state directory are deleted each time a driver instance with the same state directory is 
started. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name state-dir 

Required? no 

Case-Sensitive? platform-dependent 
Sample Value c:\novell\nds\DIBFiles 
Default Value . (current directory) 


Database Scoping Parameters 


Schema name 


This section describes the following driver parameters: 
“Schema name” on page 40 
+ “Table/view name” on page 41 
+ “Include filter expression” on page 41 


+ “Exclude filter expression” on page 42 


This parameter identifies the database schema being synchronized. A database schema is 
analogous to the name of the owner of the tables/views being synchronized. For example, if you 
wanted to synchronize two tables, usr and grp, each belonging to database user idm, you would 
enter idm as this parameter’s value. 


When using this parameter instead of “Table/view name” on page 41, you don’t need to explicitly 
schema-qualify other parameters that reference stored procedure, function, or table names unless 
they reside in a schema other than this schema name. Such names are implicitly schema-qualified 
by the driver with this schema name. In particular, "Method and timing (table-local)” on page 55 
and “Event log table name” on page 61 are affected. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name sync-schema 

Required? yes! 

Case-Sensitive? See “Undelimited Identifier Case-Sensitivity” on page 114. 
Sample Value indirect 

Default Value: (none) 


"When this parameter is used, parameter “Table/view name” on page 41 must be left empty or 
omitted from a configuration. 


IMPORTANT: Changing this value forces a resync of all objects when triggerless publication is used. 
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Table/view name 


This parameter allows you to create a logical database schema by listing the names of the logical 
database classes to synchronize. Logical database class names are the names of parent tables and 
views. It is an error to list child table names. 


This parameter is particularly useful for synchronizing with databases that do not support the 
concept of schema, such as MySQL, or when a database schema contains a large number of tables/ 
views of which only a few are of interest. Reducing the number of table/view definitions cached 
by the driver can shorten start-up time as well as reduce runtime memory utilization. 


When using this parameter instead of “Schema name” on page 40 you'll likely need to schema- 
qualify other parameters that reference stored procedure, function, or table names. In particular, 
parameters “Method and timing (table-local)” on page 55 and “Event log table name” on page 61 
are affected. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name sync-tables 

Required? yes! 

Case-Sensitive? See “Undelimited Identifier Case-Sensitivity” on 
page 114. 

Delimiters semicolon, white space, comma 

Sample Value indirect.usr; indirect.grp 

Default Value (none) 


"When this parameter is used, parameter “Schema name” on page 40 must be left empty or omitted 
from a configuration. 


Include filter expression 
This parameter is only operative when parameter “Schema name” on page 40 is used. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name include-table-filter 

Required? no 

Case-Sensitive? yes 

Sample Value idm_*. (all table/view names starting with “idm_”) 
Default Value (none) 

Leval Values (any legal Java regular expression) 
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Exclude filter expression 


This parameter is only operative when parameter “Schema name” on page 40 is used. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name exclude-table-filter 

Required? no 

Case-Sensitive? yes 

Sample Value bin”. (all table/view names starting with “bin”) 
Default Value (none) 

Legal Values (any legal Java regular expression) 


Connectivity Parameters 


This section describes the following driver parameters: 
+ “Connection initialization statements” on page 43 
+ “Use minimal number of connections?” on page 42 


+ “Connection properties” on page 43 


Use minimal number of connections? 


This parameter specifies whether the driver should use two instead of three database connections. 


By default, the driver uses three connections: one for subscription, two for publication. The 


Publisher uses one of its two connections to query for events and the other to facilitate query-back 
operations. 


When set to Boolean True, the number of required database connections is reduced to two. One is 
shared between the Subscriber and Publisher channels. It is used to process subscription and 
publication query-back events. The other is used to query for publication events. 


In previous versions, the driver was able to support bi-directional synchronization using a single 
connection. The publication algorithm was redesigned to increase performance, enable support for 
future event processing and to overcome limitations of the previous algorithm at the expense of 
requiring an additional connection. 


Property Value 

Tag Name use-single-connection 
Required? no 

Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 
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"This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is Boolean False. 


NOTE: Setting this parameter to Boolean True reduces performance. 


Connection initialization statements 


This parameter specifies what SQL statements, 1f any, should be executed immediately after 
connecting to the target database. Connection initialization statements are useful for changing 
database contexts and setting session properties. These statements are executed each time this 
product, irrespective of channel, connects or reconnects to the target database. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name connection-init 

Required? no 

Case-Sensitive? See “Undelimited Identifier Case-Sensitivity” on page 114. 
Delimiters semicolon 

Sample Value USE idm; SET CHAINED OFF 

Default Value (none) 


Connection properties 


This parameter specifies authentication properties. This parameter is useful for specifying 
properties that cannot be specified via the JDBC URL specified in the “Authentication Context” 
on page 36. 


The primary purpose of this parameter is to enable interoperability with the “Sybase Adaptive 
Server Enterprise JConnect JDBC Driver” on page 108 when using a custom SSL socket 
implementation. 


Connection properties are specified as key value pairs. The key is specified as the value to the left 
of the ‘=’ character. The value is the value to the right of the ‘=’ character. Multiple key values 
may be specified, but must be delimited by the ‘;’ character. 


When using connection properties, authentication information may be passed via the JOBC URL 
specified in parameter “Authentication Context” on page 36 or here. If specified as connection 
properties, value tokens can be used as placeholders for the database username specified in 
parameter “Authentication ID” on page 36 and password specified in parameter “Application 
Password” on page 37. For username, the token is {$username}. For password, the token is 
{Spassword}. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name connection-properties 

Required? no 

Case-Sensitive? third-party JDBC driver-dependent 
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Property Value 


Delimiters semicolon 


Sample Value USER=($username); PASSWORD={$password}; 
SYBSOCKET_FACTORY=DEFAULT 


Default Value (none) 


Compatibility Parameters 


This section describes the following driver parameters: 
+ “JDBC driver descriptor filename” on page 44 
+ “Database descriptor filename” on page 45 
+ “Use manual transactions?” on page 45 
¢ “Transaction isolation level” on page 46 
+ “Reuse statements?” on page 46 
+ “Number of returned result sets” on page 47 
+ “Enable statement-level locking?” on page 48 
+ “Lock statement generator class” on page 48 
+ “Enable referential attribute support?” on page 48 
+ “Force username case” on page 49 
+ “Left outer-join operator” on page 49 
+ “Retrieve minimal metadata?” on page 50 
+ “Function return method” on page 50 
+ “Supports schemas in metadata retrieval?” on page 50 


+ “Sort column names by” on page 51 


JDBC driver descriptor filename 


This parameter specifies the third-party JDBC descriptor file that should be used. Descriptor file 
names must not be prefixed with the underscore character ( ), as such names are reserved (for 
example, mysql jdriver.xml). Descriptor files should be placed in a jar file beginning with the 
case-insensitive prefix “jdbc” (for example, JDBCCustomConfig.jar) and placed in the jar file’s 


com/novell/nds/dirxml/driver/jdbc/db/descriptor/driver directory. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name jdbc-driver-descriptor 

Required? no 

Case-Sensitive? platform-dependent 

Sample Value my_custom_jdbc_driver_descriptor.xml 
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Property Value 


Default Value (none) 


Database descriptor filename 


This parameter specifies the database descriptor file that should be used. Descriptor file names 
must not be prefixed with the underscore character because such names are reserved (for example, 
_mysql.xml). Descriptor files should be placed in a jar file beginning with the case-insensitive 
prefix “jdbc” (for example, JDBCCustomConfig.jar) and placed in the jar file’s com/novell/ 
nds/dirxml/driver/jdbc/db/descriptor/db directory. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name jdbc-driver-descriptor 

Required? no 

Case-Sensitive? platform-dependent 

Sample Value my_custom_database_descriptor.xml 
Default Value (none) 


Use manual transactions? 
This parameter specifies whether manual or user-defined transactions should be used. 


This parameter is primarily used to enable interoperability with MySQL MyISAM table types, 
which do not support transactions. 


When set to Boolean True, the driver uses manual transactions. When set to Boolean False, each 
statement executed by the driver is executed autonomously (automatically). 


The following table lists the properties of this parameter: 


Property Value 

Tag Name use-manual-transactions 
Required? no 

Case-Sensitive? no 

Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


"This default is derived dynamically at runtime from descriptor files and database metadata. 


NOTE: To ensure data integrity, this parameter should be set to Boolean True whenever possible. 
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Transaction isolation level 


Reuse statements? 


This parameter sets the transaction isolation level for connections used by the driver. There are six 
possible values, five of which correspond to the public constants defined in the 
java.sql.Connection (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.htm) interface: 


* unsupported 

* none 

* read uncommitted 
* read committed 

* repeatable read 


* serializable 


Because some third-party drivers do not support setting a connection’s transaction isolation level 
to none, the driver also supports the additional non-standardized value of unsupported. 
PostgreSQL online documentation (http://www.postgresql.org/docs/current/static/transaction- 
iso.html) has one of the better, concise primers on what each isolation level actually means. It’s 
important to remember that the list of supported isolation levels varies by database. For a list of 
supported transaction isolation levels for supported databases, consult “Supported Transaction 
Isolation Levels” on page 114. 


We recommend using a transaction isolation level of read committed because it is the 
minimum isolation level that prevents the driver from seeing uncommitted changes (that is, dirty 
reads). 


The following table lists the properties of this parameter: 


Property Value 
Tag Name transaction-isolation-level 
Required? no 
Case-Sensitive? no 
Default Value (dynamic?) 
Legal Values unsupported 
none 


read uncommitted 
read committed 
repeatable read 
serializable 


'This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is read committed. 


This parameter specifies whether one or more java.sql.Statement (http://java.sun.com/j2se/1.5.0/ 
docs/api/java/sql/Statement.html) should be active at a time on a given connection. 


This parameter is primarily used to enable interoperability with Microsoft SQL Server 2000 Driver 
for JDBC. 
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When set to Boolean True, the driver allocates java.sql.Statement (http://java.sun.com/j2se/1.5.0/ 
docs/api/java/sql/Statement.html) once and then reuses it. When set to Boolean False, the driver 
allocates/deallocates statement objects each time they are used, ensuring that no more than one 
statement is active at a time on a given connection. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name reuse-statements 
Required? no 
Case-Sensitive? no 

Default Value (dynamic*) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


"This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is Boolean True. 


NOTE: Setting this parameter to Boolean False degrades performance. 


Number of returned result sets 


This parameter specifies how many java.sql.ResultSet (http://java.sun.com/j2se/1.5.0/docs/api/ 
java/sql/R esultSet.html) objects can be returned from an arbitrary SQL statement. 


This parameter is primarily used to avoid infinite loop conditions in “Oracle Thin Client JDBC 
Drivers” on page 106 when evaluating the results of arbitrary SQL statements. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name handle-stmt-results 

Required? no 

Sample Value one 

Default Value (dynamic?) 

Legal Values none, no (none) 
single, one (one) 


multiple, many, yes (multiple) 


"This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is multiple, many or yes. 
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Enable statement-level locking? 


This parameter specifies whether the driver should explicitly lock database resources before 
executing SQL statements. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name enable-locking 
Required? no 

Default Value 0 (no) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


Lock statement generator class 


This parameter specifies which DBLockStatementGenerator implementation should be used 
to generates the SQL statements necessary to explicitly lock database resources for a pending SQL 
statement. The DBLockStatementGenerator interface is documented in the javadocs that 
ship with this product. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name lock-generator-class 

Required? no 

Sample Value com.novell.nds.dirxml.driver.jdbc.db.lock.OraLockGenerator 
Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


"This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is com.novell.nds.dirxml.driver.¡dbc.db.lock.DBLockGenerator. 


Enable referential attribute support? 


48 


This parameter toggles whether the driver recognizes foreign key constraints between logical 
database classes. These are used to denote containment. Foreign key constraints between parent 
and child tables within a logical database class are unaffected. 


When set to Boolean True, foreign key columns are interpreted as referential. When set to Boolean 
False, foreign key columns are interpreted as non-referential. 


The primary purpose of this parameter is to ensure backward compatibility with the 1.0 version of 
this product. For 1.0 compatibility, this parameter should be set to Boolean False. 


The following table lists the properties of this parameter: 
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Property Value 


Tag Name enable-refs 
Required? no 

Default Value 1 (yes) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


Force username case 


This parameter changes the case of the driver’s username used to authenticate to the target 
database. 


The primary purpose of this parameter is to enable interoperability with the “Informix JDBC 
Driver” on page 103 when used against ANSI-compliant databases. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name force-username-case 
Required? no 

Default Value (don't force) 

Legal Values lower (to lower case) 


mixed (to mixed case) 
upper (to upper case) 
Left outer-join operator 


This parameter specifies the left outer join operator used in the triggerless publication query. It 
might be used for other purposes in the future. 


The following table lists the properties of this parameter: 


Property Value 
Tag Name left-outer-join-operator 
Required? no 
Default Value (dynamic?) 
Legal Values *= 
(+) 


LEFT OUTER JOIN 


'This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
1s LEFT OUTER JOIN. 
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Retrieve minimal metadata? 


When set to Boolean True, the driver calls only required metadata methods. When set to Boolean 
False, the driver calls required and optional metadata methods. Refer to Appendix D, 
“java.sql.DatabaseMetaData Methods,” on page 137 for a list of required and optional metadata 
methods. Optional metadata methods are required for multivalue and referential attribute 
synchronization. 


Property Value 

Tag Name minimal-metadata 
Required? no 

Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


"This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is Boolean False. 


NOTE: Setting this value to Boolean True improves startup time and third-party JDBC driver compatibility at 
the expense of functionality. 


Function return method 


This parameter specifies how data is retrieved from database functions. 


The primary purpose of this parameter is to enable interoperability with the “Informix JDBC 
Driver” on page 103. 


When set to result set, function results are retrieved through a result set. When set to return 
value, the function result is retrieved as a single, scalar return value. 


Property Value 

Tag Name function-return-method 
Required? no 

Default Value (dynamic?) 

Legal Values result set 


return value (scalar return value) 


"This default is derived dynamically at runtime from descriptor files. 


Supports schemas in metadata retrieval? 


50 


This parameter specifies whether schema names should be used when retrieving database 
metadata. 


The primary purpose of this parameter is to enable interoperability with the Informix JDBC Driver 
when used against ANSI-compliant databases. 


When set to Boolean True, schema names are used. When set to Boolean False, they are not. 
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Sort column names 


Property Value 


Tag Name supports-schemas-in-metadata-retrieval 
Required? no 

Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


'This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is Boolean True. 


by 


This parameter specifies how column position is to be determined for legacy databases that do not 
support the notion. 


The primary purpose of this parameter is to enable interoperability with legacy databases, such as 
DB2/AS400. 


Sorting columns names by hexadecimal value ensures that if a driver instance is relocated to a 
different server, it continues to function without modification. Sorting column names by platform 
or locale string collation order is more intuitive, but might require configuration changes if a driver 
instance is relocated to different server. In particular, log table column order and compound 
column name order might change. In the case of the latter, Schema-Mapping policies and object 
association values might need to be updated. In the case of the former, log table columns might 
have to be renamed. 


It is also possible to specify any fully-qualified, Java class name as long as it implements the 
java.util.Comparator (http://java.sun.com/j2se/1.5.0/docs/api/java/util/Comparator.html) 
interface and accepts java.lang.String (http://java.sun.com/j2se/1.5.0/docs/api/java/lang/ 
String.html) arguments and the class is in the runtime classpath. 


Property Value 
Tag Name column-position-comparator 
Required? no 


Default Value (dynamic?) 


Legal Values com.novell.nds.dirxml.driver.jdbc.util.config.comp.StringByteComparator (hexadecimal value) 
com.novell.nds.dirxml.driver.jdbc.util.config.comp.StringComparator (string collation order) 
(any java.util. Comparator that accepts java.lang.String arguments) 


'This default is derived dynamically at runtime from descriptor files. Otherwise, the default value 
is com.novell.nds.dirxml.driver.jdbc.util.config.comp.StringByteComparator. 


IMPORTANT: Once set, this parameter should not be changed for a given configuration. 
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Subscription Parameters 


Display Name 


Disable subscriber? 


Generation/retrieval method 


(table-global) 


Retrieval timing (table-global) 


Method and timing (table-local) 


Disable statement-level locking? 
Check update counts? 


Add default values on insert? 


The following table is a summary of all subscriber-level parameters and their properties: 


Tag Name Sample Value Default Value Required 
disable 1 (yes) 0 (no) no 
key-gen-method auto none (subscription 
event) 
key-gen-timing after (after row insertion) before (before row no 
insertion) 
key-gen usr("?=indirect.proc_idu()", (none) no 
before) 
disable-locking 1 (yes) 0 (no) no 
check-update-count 0 (no) 1 (yes) no 
add-default-values- 0 (no) (dynamic*) no 


on-view-insert 


"This default is derived dynamically at runtime from descriptor files. 
Subscription parameters fall into two major subcategories: 
+ “Uncategorized Parameters” on page 52 


+ “Primary Key Parameters” on page 54 


Uncategorized Parameters 


Disable subscriber? 


This section describes the following subscriber parameters: 
+ “Disable subscriber?” on page 52 
+ “Disable statement-level locking?” on page 53 
+ “Check update counts?” on page 53 


+ “Add default values on insert?” on page 54 


This parameter specifies whether the Subscriber channel should be disabled. 


When set to Boolean True, the Subscriber channel is disabled. When set to Boolean False, the 
Subscriber channel is active. 


Property Value 
Tag Name disable 
Required? no 
Default Value 0 (no) 
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Property Value 


Legal Values 1, yes, true (yes) 


0, no, false (no) 


Disable statement-level locking? 


This parameter specifies whether database resources should be explicitly locked on this channel 
before each SQL statement is executed. This parameter is only active if "Enable statement-level 
locking?” on page 48 is set to Boolean True. 


When set to Boolean True, database resources are explicitly locked. When set to Boolean False, 
database resources are not explicitly locked. 


Property Value 

Tag Name disable-locking 
Required? no 

Default Value 0 (no) 

Legal Values 


1, yes, true (yes) 
0, no, false (no) 


Check update counts? 


This parameter specifies whether the subscriber channel should check to see if INSERT, UPDATE 
and DELETE statements executed against a table actually updated the table. 


When set to Boolean True, update counts are checked. If nothing is updated, an exception is 
thrown. When set to Boolean False, update counts are ignored. 


This parameter should be set to Boolean False when statements are redefined in before-trigger 
logic. 


When using Microsoft SQL Server, you should use the default value because errors in trigger logic 
(that might roll back a transaction) are not propagated back to the Subscriber. 
Property Value 


Tag Name check-update-count 


Required? no 


Default Value 1 (yes) 


Legal Values 1, yes, true (yes) 


0, no, false (no) 
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Add default values on insert? 


This parameter specifies whether the Subscriber channel should provide default values when 
executing an INSERT statement against a view. 


The primary purpose of this parameter is to enable interoperability with Microsoft SQL Server 
2000. This database requires that view columns constrained NOT NULL have anon-NULL value in 
an INSERT statement. 


When set to Boolean True, default values are provided for INSERT statements executed against 
views and explicit values are not already available. When set to Boolean False, default values are 
not provided. 


Property Value 

Tag Name add-default-values-on-view-insert 
Required? no 

Default Value (dynamic?) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


"This default is derived dynamically at runtime from descriptor files. 


Primary Key Parameters 


This section describes the following subscriber parameters: 
+ “Generation/retrieval method (table-global)” on page 55 
+ “Retrieval timing (table-global)” on page 55 
+ “Method and timing (table-local)” on page 55 


When processing <add> events, which map to INSERT statements, the Subscriber uses primary 
key values to create Identity Manager associations. These parameters specify how and when the 
Subscriber obtains the primary key values necessary to construct association values. How primary 
key values are obtained is the primary key generation/retrieval method. When primary key values 
are retrieved is indicated by the retrieval timing. The following table identifies the supported 
methods and timings: 


Timing: before (row insertion) Timing: after (row insertion) 


Method: none (subscription event) x 01 
Method: driver (SELECT MAX()) x X 
Method: auto (auto-generated/identity column) 02 X 
Method: (stored procedure/function) X X 


"The Subscriber automatically overrides this timing to before. 
“The Subscriber automatically overrides this timing to after. 
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Generation/retrieval method (table-global) 


This parameter specifies how primary key values are generated or retrieved for all parent tables 
and views. This parameter is overridden by parameter "Method and timing (table-local)” on 
page 55. 


When set to none, primary key values are assumed to already exist in the subscription event. 
When set to driver, primary key values are generated using a SELECT (MAX ()+1) statement 
if retrieval timing is set to before, or a SELECT MAX () statement if retrieval timing is set to 
after. When set to auto, primary key values are retrieved via the 
java.sql.Statement.getGeneratedKeys():java.sql.ResultSet method. The 
only supported third-party JDBC driver that currently implements this method is the “MySQL 
Connector/J JDBC Driver” on page 105. 


Property Value 

Tag Name key-gen-method 
Required? no 

Default Value none (subscription event) 
Legal Values none (subscription event) 


driver (SELECT MAX()) 
auto (auto-generated/identity column) 


Retrieval timing (table-global) 


This parameter specifies when the Subscriber channel should retrieve primary key values for all 


parent tables and views. This parameter is overridden by parameter “Method and timing (table- 
local)” on page 55. 


When set to before, primary key values are retrieved before insertion. When set to after, 
primary key values are retrieved after insertion. 


Property Value 

Tag Name key-gen-timing 

Required? no 

Default Value before (before row insertion) 
Legal Values before (before row insertion) 


after (after row insertion) 


Method and timing (table-local) 


This parameter specifies the primary key generation/retrieval method and retrieval timing on a per 
parent table/view basis. It essentially maps a generation/retrieval method and retrieval timing to a 
table or view name. The syntax for this parameter mirrors a procedural programming language 
method call with multiple arguments (such as, method-name(argumentl, argument2)). 


When using “Table/view name” on page 41 you’ll probably need to explicitly schema-qualify any 
tables, views, stored procedures or functions referenced in this parameter’s value. When using 
parameter “Schema name” on page 40 tables, views, stored procedures, or functions referenced in 
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this parameter's value are implicitly schema-qualified with that schema name. If tables, views, 
stored procedures, or functions referenced in this parameter’s value are located in a different 
schema other than the implicit schema, they must be schema-qualified. 


BNF 


The BNF (Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/analyseinfo/ 
AboutBNF.html)) notation for this parameter’s value is the following: 


<key-gen> ::= <table-or-view-name> "(" <generation-retrieval-method>, 
<retrieval-timing> ")" ([<delimiter>] <key-gen>) 
<generation-retrieval-method> ::= none | driver | auto | 


""" <procedure-signature> """ | 
""" <function-signature> """ 


<table-or-view-name> ::= <legal-undelimited-database-table-or-view 
identifier> 

<delimiter> ::= ";" wt | <white-space> 

<procedure-signature> ::= <schema-qualifier> "." <stored-routine- 


name>" ("<argument-list>")" 


<function-signature> ::= "?=" <procedure-signature> 

<schema-qualifier> ::= <legal-undelimited-database-username-identifier> 

<stored-routine-name> ::= <legal-undelimited-database-stored-routin 
-identifier> 

<argument-list> ::= <column-name>{"," <column-name>) 

<column-name> ::= <column-from-table-or-view-name-previously-specified> 


Generation/Retrieval Methods 


The generation or retrieval method specifies how primary key values are to be generated, if 
necessary, and retrieved. The possible methods are enumerated below: 


none: 

By default, the Subscriber assumes eDirectory is the authoritative source of primary key values 
and that the requisite values are already present in a given <add> event. If this is the case, no 
primary values need to be generated because they already exist. They only need to be retrieved 
from the current <add> event. This is method is desirable when an eDirectory attribute, such as 
GUID, is explicitly schema-mapped to a parent table or view’s primary key column. 


Assuming the existence of a table named usr and a view named view_usr where eDirectory is 
the authoritative source of primary key values, this parameter’s value would look something like: 


usr (none); view_usr (none) 


When using this method, we recommend mapping GUID rather than CN to a parent table or view’s 
primary key column. 


driver: 
This method assumes the database is the authoritative source of primary key values for the 
specified parent table or view. 
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When prototyping or in the initial stages of deployment, it is often desirable to have the Subscriber 
generate primary key values before a stored procedure or function is written. This method can also 
be used against databases that do not support stored procedures or functions. When used in a 
production environment, however, all SQL statements generated by an <add> event should be 
contained in a serializable transaction. For additional info, refer to parameter “Transaction 
isolation level” on page 46. Instead of making all transactions serializable, you can also set 
individual transaction isolation levels using embedded SQL attributes. For additional information, 
refer to “Transaction Isolation Level” on page 91. 


For any numeric column types, the Subscriber uses a simple SELECT (MAX+1) statement for 
before timing ora SELECT MAX () statement for after timing to generate primary key values. 
For string column types, the Subscriber generates a random alpha character sequence. Other data 
types are not supported. 


Assuming the existence of a table named usr and a view named view_usr where the database 
is the authoritative source of primary key values, this parameter’s value would look something 
like: 


usr (driver); view_usr (driver) 


When using this method, we recommend omitting primary key columns from Schema Mapping 
policies and channel filters. 


auto: 
This method assumes the database is the authoritative source of primary key values for the 
specified parent table or view. 


Some databases support identity columns that automatically generate primary key values for 
inserted rows. This method retrieves auto-generated primary key values through the JDBC 3 
interface method 

java.sql.Statement .getGeneratedKeys () : java.sql.Resultset. The only 
supported third-party JDBC driver that currently implements this method is the “MySQL 
Connector/J JDBC Driver” on page 105. 


Assuming the existence of a table named usr and a view named view_usr where the database 
is the authoritative source of primary key values, this parameter’s value would look something 
like: 


usr(auto); view_usr (auto) 


When using this method, we recommend omitting primary key columns from Schema Mapping 
policies and channel filters. 


stored-procedure/function: 
This method assumes the database is the authoritative source of primary key values for the 
specified parent table or view. 


Assuming the existence of a table named usr with a primary key column named idu and a view 
named view_usr with a primary key values named pk_idu and the existence of a database 
function func last usr idu and stored procedure sp last view usr pk idu that each 
return the last generated primary key value for their respective table/view, this parameter's value 
would look something like: 


usr("?=func last usr idu()"); 
view usr("sp last view usr pk idu(pk idu)") 


In the previous examples, a parameter is passed to the stored procedure. Parameters can also be 
passed to functions, but this is not usually necessary. Unlike functions, stored procedures usually 
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return values through parameters. For stored procedures, primary key columns must be passed as 
IN OUT parameters. Non-key columns must be passed as IN parameters. 


For both stored procedures and functions, parameter order, number and data type must correspond 
to the order, number and data type of the parameters expected by the procedure or function. 


When using this method, we recommend omitting primary key columns from Schema Mapping 
policies and channel filters. 


Retrieval Timing 


Retrieval timing specifies when primary key values are retrieved. 


An <add> event always results in at least one INSERT statement against a parent table or view. 
This portion of this parameter specifies when primary key values are to be retrieved relative to the 
initial INSERT statement. 


before: 
This is the default setting. When specified, primary key values are retrieved before the initial 
INSERT statement. 


IMPORTANT: This retrieval timing is supported for all generation/retrieval methods except auto. It is required 
for the none method. 


after: 
When specified, primary key values are retrieved after the initial INSERT statement. 


IMPORTANT: This retrieval timing is supported for all generation/retrieval methods except none. It is required 
for the auto method. 


The following examples augment the previous ones by adding retrieval timing information: 
usr (none, before); view_usr(none, before) 

usr (driver, before); view_usr (driver, after) 

usr(auto, after); view_usr(auto, after) 


usr("?=func_last_usr_idu()", before); 
view usr("sp last view usr pk idu(pk idu)", after) 


The following table lists the properties of this parameter: 


Property Value 

Tag Name key-gen 

Required? no 

Case-Sensitive? See "Undelimited Identifier Case-Sensitivity” on page 114. 
Sample Value usr ("?=proc_idu()", before) 

Default Value (none) 

Leval Values (any string adhering to the BNF) 
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Publication Parameters 


The following table is a summary of all publisher-level parameters and their properties: 


Display Name Tag Name Sample Value Default Value Required 
Disable publisher? disable 1 (yes) 0 (no) no 
Disable statement-level disable-locking 1 (yes) 0 (no) no 
locking? 
Publication mode publication-mode 2 (triggerless) 1 (triggered) no 
Event log table name log-table indirect process (none) yes! 
Delete processed rows? delete-from-log 0 (no) 1 (yes) no 
Allow loopback? allow-loopback 1 (yes) 0 (no) no 
Enable future event handle-future-events 1 (yes) 0 (no) no 
processing? 
Startup option startup-option no 
Polling Interval (in seconds)  polling-interval 60 10 no? 
Time of day time-of-day 15:30:00 (none) no? 
Post polling statements post-poll-stmt DELETE FROM (none) no 
direct.direct_process 
Batch size batch-size 16 1 no 
Heartbeat interval (in pub-heartbeat-interval 10 0 no 


minutes) 


¡Required for triggered publication mode. 
“These parameters are mutually exclusive. 


Publication parameters fall into four major subcategories: 


+ “Uncategorized Parameters” on page 52 


+ “Triggered Publication Parameters” on page 61 


+ “Triggerless Publication Parameters” on page 62 


+ “Polling Parameters” on page 63 


Uncategorized Parameters 


This section describes the following publication parameters: 
+ “Disable publisher?” on page 60 


+ “Publication mode” on page 60 
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Disable publisher? 


This parameter specifies whether the Publisher channel should be disabled. If it is disabled, the 
Publisher channel does not establish a connection to the target database. 


When set to Boolean True, the Publisher channel is disabled. When set to Boolean False, the 
Publisher channel is active. 


Property Value 
Tag Name disable 
Required? no 
Default Value 0 (no) 
Legal Values 


1, yes, true (yes) 
0, no, false (no) 


Disable statement-level locking? 


This parameter specifies whether database resources should be explicitly locked on this channel 
before each SQL statement is executed. This parameter is only active if driver parameter “Enable 
statement-level locking?” on page 48 is set to Boolean True. 


When set to Boolean True, database resources are explicitly locked. When set to Boolean False, 
database resources are not explicitly locked. 


Property Value 

Tag Name disable-locking 
Required? no 

Default Value 0 (no) 

Legal Values 


1, yes, true (yes) 
0, no, false (no) 


Publication mode 


This parameter specifies which publication algorithm should be used. 


When set to I (triggered), the Publisher polls the event log table for events. When set to 2 


(triggerless), the Publisher dredges all tables/views in the synchronization schema for changes and 
synthesizes events. 


The following table lists the properties of this parameter: 


Property Value 


Tag Name publication-mode 


Required? no 


Default Value 1 (triggered) 


Legal Values 1 (triggered) 
2 (triggerless) 
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Triggered Publication Parameters 


Event log table name 
This parameter specifies the name of the event log table where publication events are stored. 
The table specified here must conform to the definition of "The Event Log Table” on page 79. 


When using “Table/view name” on page 41 you’ll probably need to explicitly schema-qualify this 
table name. When using “Schema name” on page 40 this table name is implicitly schema-qualified 
with that schema name. If this table is located in a schema other than the implicit schema, it must 
be schema-qualified. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name log-table 

Required? no! 

Case-Sensitive? See “Undelimited Identifier Case-Sensitivity” on page 114. 
Sample Value eventlog 

Default Value (none) 


This parameter is required if “Publication mode” on page 60 is set to 1 (triggered publication). 


Delete processed rows? 
This parameter specifies whether processed rows are deleted from the event log table. 


When set to a Boolean True, processed rows are deleted. When set to Boolean False, processed 
row's status field values are updated. 


In order to mitigate the performance hit caused when processed rows remain in the event log table, 
We recommend moving them into a history table periodically. One way of doing this is by calling 
a clean-up stored procedure via the parameter “Post polling statements” on page 64. Alternatively, 
you could place a before-delete trigger on the event log table to intercept delete events executed 

against the event log table and move deleted rows to a history table before they are deleted from 
the event log table. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name delete-from-log 
Required? no 

Default Value 0 (no) 

Legal Values 1, yes, true (yes) 


0, no, false (no) 


NOTE: Setting this parameter to Boolean False degrades publication performance unless processed rows 
are periodically removed from the event log table by some means. 
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Allow loopback? 


This parameter specifies whether events caused by the driver’s database user account should be 
published. 


When set to a Boolean True, loopback events are published. When set to Boolean False, loopback 
events are ignored. 


The following table lists the properties of this parameter: 


Property Value 
Tag Name allow-loopback 
Required? no 


Default Value 0 (no) 


Legal Values 1, yes, true (yes) 


0, no, false (no) 


NOTE: Setting this parameter to Boolean True may degrade performance because extraneous events may 
be published. 


Enable future event processing? 


This parameter specifies whether rows in the event log table should be ordered and processed by 
insertion order (the record id column) or chronologically (the event time column). 


When set to Boolean True, rows in the event log table are published by order of insertion. When 
set to Boolean False, rows in the event log table are published chronologically. 


The following table lists the properties of this parameter: 


Property Value 
Tag Name handle-future-events 
Required? no 


Default Value 0 (no) 


Legal Values 1, yes, true (yes) 


0, no, false (no) 


Triggerless Publication Parameters 


Startup option 


This parameter specifies what should happen when a triggerless Publisher starts. 


When set to a 1, all past and present changes are published. When set to 2, past and present changes 
are ignored. When set to 3, all objects are assumed to have changed and are republished. 


The following table lists the properties of this parameter: 
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Property Value 


Tag Name startup-option 
Required? no 

Default Value 1 (process all changes) 
Legal Values 1 (process all changes) 


2 (process future changes only) 
3 (resync all objects) 


Polling Parameters 


Polling interval (in seconds) 


This parameter specifies how many seconds of inactivity should elapse between polling cycles. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name polling-interval 
Required? no 

Default Value 10 (seconds) 
Legal Values 1-604800 (1 week) 


NOTE: We recommend setting this value to no less than 10 seconds. 


Publication time of day 


This parameter specifies at what time, each day, publication should begin. Time is understood to 
mean server local time; that is, the time on the server where the driver is running. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name time-of-day 

Required? no 

Sample Value 13:00:00 (1PM) 

Default Value (none) 

Legal Values hh:mm:ss (h = hour, m = minute, s = second) 


NOTE: This parameter overrides parameter “Polling interval (in seconds)” on page 63. 
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Post polling statements 


This parameter specifies the SQL statements that should be executed at the end of each active 
polling cycle. An active polling cycle is one where some publication activity has occurred. 


The primary purpose of this parameter is to allow cleanup of the event log table following 
publication activity. 


You'll likely need to explicitly schema-qualify any database objects (for example, tables, stored 
procedures, functions, etc.) referenced in these statements. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name post-poll-stmt 

Required? no 

Case-Sensitive? See “Undelimited Identifier Case-Sensitivity” on 
page 114. 

Delimiters semicolon 

Sample Value DELETE FROM direct.direct_process 

Default Value (none) 

Legal Values (any set of legal SQL statements) 


Batch size 


This parameter specifies how many events should be sent in a single publication document. 


Basically, the larger the batch, the better the performance. Larger batches necessitate fewer trips 
across the network in both directions. More events in a single document requires fewer trips from 
the Publisher to the Identity Manager engine (assuming query-back events are not being used). 
Larger batches also minimize the number of trips from the Publisher to the database (assuming the 
third-party JDBC driver and database support batch processing). Lastly, larger batches require 
fewer commits to state files in the local file system, which can also be costly. 


This parameter defines an upper bound and the Publisher may override the specified value under 
certain conditions. The upper bound of 128 was chosen to minimize the likelihood of overflowing 
the Java heap and to mitigate delaying termination of the Publisher thread on driver shutdown. 


The following table lists the properties of this parameter: 


Property Value 

Tag Name batch-size 
Required? no 
Default Value 1 

Legal Values 1 to 128 
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Heartbeat interval (in minutes) 


This parameter specifies how many minutes of Publisher inactivity should elapse before the 
Publisher should send a heartbeat document. In practice, more than the number of minutes 
specified can elapse. That is, this parameter defines a lower bound. The Publisher only sends a 
heartbeat document if the Publisher has been inactive for the specified number of minutes. Any 
publication document sent is, in effect, a heartbeat document. 


The following table lists the properties of this parameter: 


Trace Levels 


Property Value 

Tag Name pub-heartbeat-interval 

Required? no 

Default Value 0 

Legal Values 0 to 2,147,483,647 (java.lang.Integer.MAX_VALUE) 


In order to see debugging output from the driver, you need to add a DirXML-DriverTraceLevel 
attribute value from 1 to 7 on the driver set containing the driver instance. This attribute is 
commonly confused with the DirXML-XSL TraceLevel attribute. For more information on driver 
set trace levels, refer to the Identity Manager Administration Guide (http://www.novell.com/ 
documentation). 


The driver supports the following seven trace levels: 
1. Minimal tracing. 
. Database properties 
. Connection status, SQL statements, event log records 
. Verbose output 
. Database resource allocation/deallocation, triggerless publication state 
. JDBC API (invoked methods, passed arguments, returned values, etc.) 
. Third-party JDBC driver 


NY HD Wn A U N 


Levels 6 and 7 are particularly useful for debugging third-party drivers. 


Configuring Third-Party JDBC Drivers 


The following guidelines will assist you in configuring third-party drivers. For specific 
configuration instructions, refer to your third-party driver’s documentation. 


+ Use the latest version of the driver available. 


¢ Third-party driver behavior might be configurable. In many cases, incompatibility issues can 
be resolved by adjusting the driver’s JDBC URL properties. 


+ When dealing with international characters, it is often necessary to explicitly specify the 
character encoding used by the database to third-party drivers by appending a property string 
to the end of the driver's JOBC URL. Properties usually consist of a property keyword and 


Configuring the IDM Driver for JDBC 65 


66 


character encoding value (for example, jdbc:odbc:mssql;charSet=Big5). The property 
keyword might vary among third-party drivers. 


The possible character encoding values are defined by Sun. Refer to Sun’s Supported 
Encoding Web site (http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html) for 


more information. 


The following table lists the recommended settings for maximum driver compatibility. These 
settings are useful when using an unsupported third-party driver during initial configuration. 


Parameter Name 


delimited-list-of-table-names 


Table/view name(s) 


Reuse statements? 

Use manual transactions? 

Use minimal number of connections? 
Retrieve minimal metadata? 


Number of returned result sets 
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Compatibility Value 


0 (no) 
0 (no) 
yes 

1 (yes) 


one 


Advanced Configuration 


After installing the sample driver configuration, you need to customize it for specialized use. This 
section contains important conceptual information, sample configurations, and so forth to help you 


configure this product. 
+ “Schema Mapping” on page 67 
+ "The Event Log Table” on page 79 
+ “XDS Event to SQL Statement Mapping” on page 78 
+ “Embedding SQL Statements in XDS Events” on page 87 


Schema Mapping 


The following table shows a high-level view of how the driver maps Novell? eDirectory™ objects 


to database objects. 


eDirectory Object Database Object 
Tree Schema 

Class Table/View 
Attribute Column 
Association Primary Key 


Logical Database Classes 


A logical database class is the set of tables or the view used to represent an eDirectory class in a 
database. A logical database class can consist of a single view or one parent table and zero or more 


child tables. The name of a logical database class is the name of the parent table or view. 


Indirect Synchronization 


In an indirect synchronization model, the driver maps the following: 


eDirectory Object Database Object 
Classes Tables 
Attributes Columns 
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eDirectory Object 


1 Class 


Single-value attribute 


Multivalue attribute 
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Database Object 

1 parent table 

and 

0 or more child tables 

Parent table column 

Parent table column (holding delimited values) 
or 


Child table column (preferred) 


In the following example, the logical database class usr consists of one parent table usr and two 
child tables usr_phone and usr_faxno. Logical class usr is mapped to the eDirectory class 


User. 
CREATE TABLE indirect.usr 
( 
idu INTEGER NOT NULL, 
fname VARCHAR2 (64), 
lname CHAR (64), 
pwdminlen NUMBER (4), 
pwdexptime DATE, 
disabled NUMBER (1), 
username VARCHAR2 (64), 
loginame VARCHAR2 (64), 
photo LONG RAW, 
manager INTEGER, 
CONSTRAINT pk_usr_idu PRIMARY KEY (idu), 
CONSTRAINT fk_usr_manager FOREIGN KEY (manager) 
REFERENCES indirect.usr(idu) 
) 
CREATE TABLE indirect.usr_phone 
( 
idu INTEGER NOT NULL, 
phoneno VARCHAR2 (64) NOT NULL, 
CONSTRAINT fk_phone_idu FOREIGN KEY (idu) 
REFERENCES indirect.usr(idu) 


TABLE 


idu INTEGER NOT 
VARCHAR2 (64) NOT 


indirect.usr_fax 


NULL, 
NULL, 


CONSTRAINT fk_fax_idu FOR 


EIGN KEY 


REFERENCES indirect.usr (idu) 


<rule name="Schema Mapping Rule"> 


<attr-name-map> 
<class-name> 


<nds-name>User</nds-name> 
<app-name>indirect.usr</app-name> 


</class-name> 
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(idu) 


Parent Tables 


<attr-name class-name="User"> 
<nds-name>Given Name</nds-name> 


<app-name>fname</app-name> 
</attr-name> 


<attr-name class-name="User"> 
<nds-name>Surname</nds-name> 


<app-name>lname</app-name> 
</attr-name> 


<attr-name class-name="User"> 


<nds-name>Password Expiration Time</nds-name> 
<app-name>pwdexpt ime</app-name> 
</attr-name> 


<attr-name class-name="User"> 
<nds-name>jpegPhoto</nds-name> 
<app-name>photo</app-name> 
</attr-name> 


<attr-name class-name="User"> 
<nds-name>manager</nds-name> 
<app-name>manager</app-name> 
</attr-name> 


<attr-name class-name="User"> 
<nds-name>Password Minimum Length</nds-name> 
<app-name>pwdminlen</app-name> 

</attr-name> 


<attr-name class-name="User"> 

<nds-name>Facsimile Telephone Number</nds-name> 
<app-name>usr fax.faxno</app-name> 

</attr-name> 


<attr-name class-name="User"> 
<nds-name>Telephone Number</nds-name> 
<app-name>usr phone.phoneno</app-name> 
</attr-name> 


<attr-name class-name="User"> 
<nds-name>Login Disabled</nds-name> 
<app-name>disabled</app-name> 
</attr-name> 
</attr-name-map> 
</rule> 


Parent tables are tables with an explicit primary key constraint that contains one or more columns. 
In a parent table, an explicit primary key constraint is required so that the driver knows which 
fields to include in an association value. 


CREATE TABLE indirect.usr 
( 


idu INTEGER NOT NULL, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 
) 


The following table contains sample data for table indirect .usr. 


idu fname Iname 


1 John Doe 


The resulting association for this row would be: 
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idu=1,table=usr, schema=indirect 


NOTE: The case of database identifiers in association values is determined dynamically at runtime from 
database metadata. 


Parent Table Columns 


Child Tables 


Parent table columns can contain only one value. As such, they are ideal for mapping single-value 
eDirectory attributes, such as mapping the single-value eDirectory attribute Password Minimum 
Length to the single-valued parent table column pwdminlen. 


Parent table columns are implicitly prefixed with the schema name and name of the parent table. 
It is not necessary to explicitly table-prefix parent table columns. For example, 
indirect.usr.fname is equivalent to fname for schema mapping purposes. 


<rule name="Schema Mapping Rule"> 
<attr-name-map> 
<class-name> 
<nds-name>User</nds-name> 


<app-name>indirect.usr</app-name> 

</class-name> 

<attr-name class-name="User"> 
<nds-name>Given Name</nds-name> 
<app-name>fname</app-name> 

</attr-name> 

</attr-name-map> 
</rule> 


Large binary and string data types should usually be mapped to parent table columns. In order to 
map to a child table column, data types must be comparable in an SQL statements. Large data types 
usually cannot be compared in SQL statements. 


Large binary and string data types can be mapped to child table columns if <remove-value> 
events on these types are transformed in policy into a <remove-all-values> element 
followed by a series of <add-value> elements, one for each value. 


A child table is a table that has a foreign key constraint on its parent table”s primary key, linking 
the two tables together. The columns that comprise the child table’s foreign key can have different 
names than the columns in the parent table’s primary key. 


The following example shows the relationship between parent table usr and child tables 
usr_phone and usr_faxno: 


CREATE TABLE indirect.usr 


( 


idu INTEGER NOT NULL, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


CREATE TABLE indirect.usr_phone 


idu INTEGER NOT NULL, 
phoneno VARCHAR2 (64) NOT NULL, 
CONSTRAINT fk phone idu FOREIGN KEY (idu) 
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REFERENCES indirect .usr (idu) 


CREATE TABLE indirect.usr_fax 


idu INTEGER NOT NULL, 

faxno VARCHAR2 (64) NOT NULL, 

CONSTRAINT fk_fax_idu FOREIGN KEY (idu) 
REFERENCES indirect .usr (idu) 


) 
NOTE: All columns in a child table should be constrained NOT NULL. 


The first constrained column in a child table identifies the parent table. In the above example, the 
constrained column in child table usr_phone is idu. The only purpose of this column is to relate 
tables usr_phone and usr. Because constrained columns do not contain any useful information, 
they should be omitted from publication triggers and Schema Mapping policies. 


The unconstrained column is the column of interest. It represents a single, multivalue attribute. In 
the above example, the unconstrained columns are phoneno and faxno. Because unconstrained 
columns can hold multiple values, they are ideal for mapping multivalue eDirectory attributes. For 
example, mapping the multivalue eDirectory attribute Telephone Number to 
usrphone.phoneno. 


The following table contains sample data for indirect .usr_phone. 


idu phoneno 
1 111-1111 
1 222-2222 


Like parent table columns, child table columns are implicitly schema-prefixed. Unlike parent table 
columns, however, child table column name must be explicitly prefixed with the child table name 
(for example, usr phone.phoneno). Otherwise, the driver implicitly interprets column 
phoneno as usr.phoneno, not usr_phone.phoneno. 


<rule name="Schema Mapping Rule"> 
<attr-name-map> 
<class-name> 
<nds-name>User</nds-name> 
<app-name>indirect.usr</app-name> 
</class-name> 
<attr-name class-name="User"> 
<nds-name>Facsimile Telephone Number</nds-name> 
<app-name>usr fax.faxno</app-name> 
</attr-name> 
<attr-name class-name="User"> 
<nds-name>Telephone Number</nds-name> 
<app-name>usr phone.phoneno</app-name> 
</attr-name> 
</attr-name-map> 
</rule> 


NOTE: Each multivalue, eDirectory attribute should be mapped to a different child table. 
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Referential Attributes 


Referential containment can be represented in the database through the use of foreign key 
constraints. Referential attributes are columns within a logical database class that refer to the 
primary key columns of parent tables in the same logical database class or those of other logical 
database classes. 


Single-Value, Referential Attributes 


Two parent tables can be related through a single-value parent table column. This column must 
have a foreign key constraint pointing to the other parent table’s primary key. The following 
example relates a single parent table usr to itself: 


CREATE TABLE indirect.usr 
( 
idu INTEGER NOT NULL, 


manager INTEGER, 

CONSTRAINT pk_usr_idu PRIMARY KEY (idu), 

CONSTRAINT fk_usr_manager FOREIGN KEY (manager) 
REFERENCES indirect .usr (idu) 


) 


NOTE: Single-valued, referential columns should be nullable. 


<rule name="Schema Mapping Rule"> 
<attr-name-map> 
<class-name> 


<nds-name>User</nds-name> 
<app-name>indirect.usr</app-name> 

</class-name> 

<attr-name class-name="User"> 
<nds-name>manager</nds-name> 
<app-name>manager</app-name> 

</attr-name> 

</attr-name-map> 
</rule> 


The interpretation of the above example is that each user can have one and only one manager who 
himself is a user. 


Multivalue, Referential Attributes 
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Two parent tables can be related through a common child table. This child table must have a 
column constrained by a foreign key pointing to the other parent table’s primary key. The 
following example relates two parent tables usr and grp through a common child table member. 


CREATE TABLE indirect.usr 
( 


idu INTEGER NOT NULL, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


) 


CREATE TABLE indirect.grp 
( 
idg INTEGER NOT NULL, 


CONSTRAINT pk_grp_idg PRIMARY KEY (idg) 
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CREATE TABLE indirect.grp member 


idg INTEGER NOT NULL, 

idu INTEGER NOT NULL, 

CONSTRAINT fk_member_idg FOREIGN KEY (idg) 
REFERENCES indirect .grp(idg), 

CONSTRAINT fk_member_idu FOREIGN KEY (idu) 
REFERENCES indirect .usr (idu) 


) 


NOTE: All columns in a child table should be constrained NOT NULL. 


<rule name="Schema Mapping Rule"> 
<attr-name-map> 
<class-name> 
<nds-name>Group</nds-name> 
<app-name>indirect.grp</app-name> 
</class-name> 
<class-name> 
<nds-name>User</nds-name> 
<app-name>indirect .usr</app-name> 
</class-name> 
<attr-name class-name="Group"> 
<nds-name>Member</nds-name> 
<app-name>grp member.idu</app-name> 
</attr-name> 
</attr-name-map> 
</rule> 


The first constrained column in a child table determines which logical database class child table 
grp member belongs to. In the above example, grp member is considered to be part of logical 
database class grp. grp member is said to be a proper child of grp. The second constrained 


column in a child table is the multi-value referential attribute. 


In the following example, the order of the constrained columns has been reversed so grp member 


is part of class usr. To more accurately reflect the relationship, table grp member has been 


renamed to usr mbr of. 


CREATE TABLE indirect.usr 
( 
idu INTEGER NOT NULL, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


) 


CREATE TABLE indirect.grp 
( 


idg INTEGER NOT NULL, 


CONSTRAINT pk_grp_idg PRIMARY KEY (idg) 


CREATE TABLE indirect.usr_mbr_of 


idu INTEGER NOT NULL, 
idg INTEGER NOT NULL, 
CONSTRAINT fk mbr of idu FOREIGN KEY (idu) 


REFERENCES indirect .usr (idu) ON DELETE CASCADE, 


CONSTRAINT fk_mbr_of_idg FOREIGN KEY (idg) 


REFERENCES indirect.grp(idg) ON DELETE CASCAD 


[| 


Advanced Configuration 


73 


<rule name="Schema Mapping Rule"> 
<attr-name-map> 
<class-name> 
<nds-name>Group</nds-name> 
<app-name>indirect.grp</app-name> 
</class-name> 
<class-name> 
<nds-name>User</nds-name> 
<app-name>indirect .usr</app-name> 
</class-name> 
<attr-name class-name="User"> 
<nds-name>Group Membership</nds-name> 
<app-name>usr_mbr_of.idg</app-name> 
</attr-name> 
</attr-name-map> 
</rule> 


In databases where there is no notion of column position (such as DB2/AS400), order is 
determined by sorting column names by string or hexadecimal value. For additional information, 
see parameter “Sort column names by” on page 51. 


In general, it is only necessary to synchronize bidirectional, multivalue, referential attributes as 
part of one class or the other, not both. If you want to synchronize referential attributes for both 
classes, you need to construct two child tables, one for each class. For example, if you want to 
synchronize eDirectory attributes Group Membership and Member, you would need two child 
tables. 


In practice, when synchronizing User and Group classes, we recommend that you synchronize the 
Group Membership attribute of class User instead of the Member attribute of class Group. It is 
usually more efficient to synchronize the group memberships of a single user than all members of 
a single group. 


Direct Synchronization 
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In a direct synchronization model, the driver maps the following: 


eDirectory Object Database Object 
Classes Views 
Attributes View Columns 
1 Class View 
Single-value attribute View Column 
Multivalue attribute View Column 


The update capabilities of views vary between databases. Most databases allow views to be 
updated when they are comprised of a single base table. If views are strictly read-only, then they 
cannot be used for subscription. Some databases allow update logic to be defined on views in 
instead-of-triggers, which allow a view to join multiple base tables and still be updated. For a list 
of databases that support instead-of-triggers, refer to “Database Features” on page 112. 
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View Column Meta-Identifiers 


A view is a logical table. Unlike tables, views do not physically exist in the database. As such, 
views cannot have traditional primary key/foreign key constraints. To simulate these constructs, 
this product embeds constraints and other metadata in view column names. The difference 
between these constraints and traditional ones is that the former are not enforced at the database 
level. They are an application-level construct. 


For example, in order to identify to the driver which fields to use when constructing association 
values, a primary key constraint is placed on a parent table. The corollary to this for a view is to 
prefix one or more column names with pk (case-insensitive). 


The following table lists the constraint prefixes that can be embedded in view column names. 


Constraint Prefixes (case-insensitive) Interpretation 


pk_ primary key 
fk_ foreign key 
Sv. single-value 
mv multi-value 


The following example views contains all of these constraint prefixes: 


CREATE VIEW direct.view usr 


pk idu, -- primary key column; implicitly single-valued 
sv fname, -- single-valued column 

mv phoneno, multi-valued column 

fk idu manager, self-referential foreign key column; refers 


=s to primary key column idu in view usr; 
ss implicitly single-valued 
fk mv idg mbr of -- extra-referential foreign key column; refers 
== to primary key column idg in view_grp; 
=- multi-valued 


CREATE VIEW direct.view_grp 


pk_idg, -- primary key column; implicitly single-valued 
fk mv idu mbr xtra-referential foreign key column; refers 
SS to primary key column idu in view usr; 
== multi-valued 


BNF 


The BNF (Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/analyseinfo/ 
AboutBNF.html)) notation for view column meta-identifiers: 


<view-column-name> ::= [<meta-info>] <column-name> 


<column-name> ::= <legal-unquoted-database-identifier> 


Advanced Configuration 75 


<meta-info> ::= <referential> | <non-referential> 


<non-referential> ::= [<single-value> | <multiple-value>] 
<single-value> ::= "sv " 

<multiple-value> ::= "mv " 

<referential> ::= <primary-key> | <foreign-key> 
<primary-key> ::= "pk " [<single-value>] [<column-group-id>] 


[<referenced-column-name>] 


<column-group-id> ::= <non-negative-integer> "_" 
<referenced-column-name> ::= "_" <column-name> "__" 
<foreign-key> ::= "fk_" [<non-referential>] [<column-group-id>] 


<referenced-column-name> 


Normalized Forms 


By default, all view column names are single-valued, so explicitly specifying the sv_ prefix in a 
view column name is redundant. For example, sv fname and fname are equivalent forms of the 
same column name. 


Also, primary key column names implicitly refer to themselves, thus it is redundant to specify the 
referenced column name. For example, pk idu is equivalent to pk__idu__idu. 


There are several normalized forms of view meta-identifiers used by the driver. Database native 
form is the column name as declared in the database. The other form is schema mapping form. This 
form is the form returned when the application schema is returned by the driver. Database native 
form is usually much more verbose and contains all necessary meta information. Schema mapping 
1s much more concise since much of the meta information included in database native form is 
represented in XDS XML and not in the identifier. The only meta information preserved in schema 
mapping form are the referential prefixes pk and fk . This is done to ensure backward 
compatibility. 


Examples of each form are provided in the following table: 


Database Native Form Schema Mapping Form 
pk_idu pk_idu 

sv_fname fname 

mv phoneno phoneno 

fk mv idg mbr of fk mbr of 


Equivalent Forms 


For the driver, view column name equivalency is determined without respect to meta information. 
For example, pk idu is equivalent to idu and fk mv idg mbr of is equivalent to 
mbr of. Any variant form of a view meta column identifier can be passed to the driver at runtime. 


Primary Key Columns 


Primary key column names must be unique between all views in the synchronization schema. 
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Schema Mapping 


Schema mapping for views and view columns is equivalent to that used for parent tables and parent 
table columns. 


Synchronizing Primary Key Columns 


When the database is the authoritative source of primary key columns, they should generally be 
omitted from the Publisher and Subscriber filters, Schema Mapping policies, and publication 
triggers. 


When the eDirectory is the authoritative source of primary key columns, they should be included 
in the Subscriber filter and Schema Mapping policies and omitted from the Publisher filter and 
publication triggers. Also, GUID rather than CN is recommended for use as a primary key. CN is 
multivalue and can change. GUID has a single-value and is static. 


Synchronizing Multiple Classes 


When synchronizing multiple eDirectory classes, it is necessary to synchronize each class to a 
different parent table or view. Each logical database class must have a unique primary key column 
name. This common column name is used by the Publisher to identify all rows in the event log 
table pertaining to a single logical database class. For example, logical database classes usr and 
grp each have a unique primary key column name. 


CREATE TABLE usr 
( 


idu INTEGER NOT NULL, 
lname VARCHAR2 (64) NOT NULL, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


CREATE TABLE grp 


idg INTEGER NOT NULL, 


CONSTRAINT pk_grp_idg PRIMARY KEY (idg) 
); 


Mapping Multivalue Attributes to Single-Value Database Fields 


By default, the driver assumes that all eDirectory attributes mapped to parent table columns or 
view columns have a single value. Because the driver is unaware of the eDirectory schema, it has 
no way of knowing whether an eDirectory attribute has a single value or multivalue. Accordingly, 
multivalue and single-value attribute mappings are handled identically. 


The driver implements the Most Recently Touched (MRT) algorithm with regard to single-value 
parent table or view columns. An MRT algorithm ensures that the most recently added attribute 
value or most recently deleted attribute value is stored in the database. The algorithm is adequate 
if the attribute in question has a single value, and has some undesirable consequences if the 
attribute has multiple values. 


When a value is deleted from a multivalue attribute, the database field it is mapped to is set to 
NULL and remains NULL until another value is added. Several solutions to this undesirable 
behavior are outlined below. 
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+ 


The preferred solution is to extend the eDirectory schema so that only single value attributes 
are mapping to parent table or view columns. 


* 


For indirect synchronization, map each multivalue attribute to its own child table. 


+ 


For both direct or indirect synchronization, use policy to delimit multiple values before 
inserting them into a table or view column. 


+ Implement a first or last value per replica policy in style sheets using methods provided in the 
com.novell.nds.indirect.driver.jdbc.util.MappingPolicy class. Under a 
first-value-per-replica (FPR) policy, the first attribute value on the eDirectory replica is 
always synchronized. Under a last-value-per-replica (LPR) policy, the last attribute value on 
a replica is always synchronized. 


The sample driver configuration can be configured through global configuration values to use 
either a FPR or LPR mapping policies. Multivalue to single-value attribute mapping policies 
are contained in the Subscriber Command Transformation policy container. The sample 
driver configuration maps the multivalue eDirectory attributes Given Name and Surname to 
the single value columns fname and 1name respectively. 


XDS Event to SQL Statement Mapping 


The following table summarizes how the Subscriber maps XDS events to DML SQL statements 
for indirect synchronization: 


XML Event SQL Equivalent 
<add> 0 or more select statements, depending upon matching policy 
1 parent table insert statement for all single value <add-attr> elements 


0 or 1 stored procedure/function calls to retrieve primary key values before 
or after the parent table insert statement 


1 child table insert statement for each multivalue <add-attr> element 


<modify> 1 parent table update statement for each single value <add-value> or 
<remove-value> element 


1 child table insert statements for each multivalue <add-value> element 


1 child table delete statement for each <remove-value> element 


<delete> 1 parent table delete statement 


1 delete statement for each child table 


<query> 1 parent table select statement 


1 select statement for each child table 


<move> 0 statements unless bound to embedded SQL statements 
<rename> 

<modify-password> 

<check-object-password> 
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The following table summarizes how the Subscriber maps XDS events to DML SQL statements 


for direct synchronization: 


XML Event SQL Equivalent 
<add> 0 or more select statements, depending upon matching policy 
1 view insert statement for all single value <add-attr> element 
0 or 1 stored procedure/function calls to retrieve primary key values before 
or after the view insert statement 
1 view insert statement for each multivalue <add-attr> element 
<modify> 1 view update statement for each single value <add-value> or <remove- 
value> element 
1 view insert statements for each multivalue <add-value> element 
1 view delete statement for each <remove-value> element 
<delete> 1 view delete statement 
<query> 1 view select statement 
<move> O statements unless bound to embedded SQL statements 
<rename> 


<modify-password> 
<check-object-password> 


The Event Log Table 


The event log table is where publication events are stored. This section discusses the structure and 
limitations of the event log table. 


You can customize the name of the event log table and its columns to avoid conflicts with reserved 
database keywords. The order, number, and data types of its columns, however, are fixed. In 
databases where there is no concept of column position, order is determined by the parameter “Sort 
column names by” on page 51. 


Events in this table can be ordered either by order of insertion (the record_id column) or by the 
chronologically (the event_time column). Ordering events chronologically allows event 
processing to be delayed. To order publication events chronologically, set parameter “Enable 
future event processing?” on page 62 to Boolean True. 


Event Log Columns 


This section describes columns in the event log table. Columns are ordered by position. 


l. record id 


The record id column is used to uniquely identify rows in the event log table and order 
publication events. This column must contain sequential, ascending, positive, unique integer 
values. Gaps between record id values no longer prematurely end a polling cycle. 


2. status 


The status column indicates the state of a given row. The permitted values are: 
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Character Value Interpretation 


N new 

S success 
W warning 
E error 

F fatal 


All rows inserted into the event log table must have a status value of ”N” in order to be 
processed. The remainder of the status characters are used solely by the Publisher to designate 
processed rows. All other characters are reserved for future use. 


NOTE: Status values are case-sensitive. 


3. event type 


Values in this column must be between 1 and 8. All other numbers are reserved for future use. 


The following table describes each event type and what it means: 


Event Type Interpretation 

1 insert field 

2 update field 

3 update field (remove all values) 
4 delete row 

5 insert row (query-back) 

6 update row (query-back) 

7 insert field (query-back) 

8 update field (query-back) 


Event types can be categorized into four major categories, some of which overlap. The 
following table describes each category and indicates which event types are members: 


Event Category Event Types 
Per-field (attribute) 1,2,3,7,8 
Per-row (object) 4,5,6 
Non-query-back 1, 2, 3,4 
Query-back 5,6,7,8 


Per-field, non-query-back 1, 2,3 


Per-field, query-back 
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Event Category Event Types 


Per-row, non-query-back 4 


Per-row, query-back 5,6 


In general, a combination of event types from each category yields the best time, space, and 
complexity tradeoffs. 


. event time 


This column serves as an alternative ordering column to record, id. It contains the effective 
date of the event. It must not be NULL. In order for this column to become the ordering 
column, the parameter “Enable future event processing?” on page 62 must be set to Boolean 
True. 


. perpetrator 


This column identifies the database user who instigated the event. A NULL value is interpreted 
as a user other than the driver user. As such, rows with a NULL value or value not equal to the 
driver’s database username are published. Rows with a value equal to the driver’s database 

username are not published unless the Publisher parameter “Allow loopback?” on page 62 is 
set to Boolean True. 


. table_name 
The name of the table or view where the event occurred. 
. table key 


Values for this column must be formatted exactly the same in all triggers for a logical database 
class. The BNF or Backus Naur Form (http://cui.unige.ch/db-research/Enseignement/ 
analyseinfo/AboutBNF.html) of this parameter is defined below: 


<table-key> ::= <unique-row-identifier> ("+" <unique-row-identifier>) 


<unique-row-identifier> ::= <primary-key-column-name> "=" <value> 


For example, for the usr table referenced throughout this chapter, this column's value might 
look like idu=1. 


For the view usr view used througout this chapter, this column’s value might look like 
pk empno=1. 


Differences in padding or formatting might result in out-of-order event processing. For 
performance reasons, you should remove any unnecessary white space from numeric values. 
(For example, "idu=1" is preferred over "idu= 1"). 


NOTE: Primary key values placed in the table key field should be delimited (that is, double-quoted) if 
they contain the following characters: ,;"+=|"<>. 


. Column name 


The name of the column that was changed. This column is used only for per-field (1-3, 7-8) 
event types. Even though this column is used only for per-field event types, it must always 
be present in the event log table. If it is missing, the Publisher will not start. 


. Old value 


The field's old value. This column is used only for per-field, non-query-back event types (1- 
3). Even though this column is only used for these event types, it must always be present in 
the event log table. If it is missing, the Publisher will not start. 
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Event Types 


event type 


1 


10. new value 


The field's new value. This column is used only by per-field, non-query-back event types (1- 
3). Even though this column is only used for these event types, it must always be present in 
the event log table. If missing, the Publisher will not start 


This section describes in greater detail the different event log table event types and how they are 
interpreted by the publisher. 


The following table shows the basic correlation between publication event types and the XDS 
XML generated by the publisher. 


Event Type Resulting XDS 
insert <add> 

update <modify> 
delete <delete> 


The following example illustrates the XML generated by the publisher for events logged on the 
usr table for each possible event type. 


CREATE TABLE indirect.usr 
( 


idu INTEGER NOT NULL, 
fname VARCHAR2 (64), 
photo LONGRAW, 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


i 


The following table shows the initial contents of usr after a new row has been inserted: 


idu fname Iname photo 


1 Jack Frost OxAAAA 


The following table shows the current contents of usr after the row has been updated: 


idu fname Iname photo 


1 John Doe OxBBBB 


1. Insert Field 


The table below shows the contents of the event log table after a new row is inserted into table 
usr. The value for column photo has been Base64-encoded. The Base64-encoded 
equivalent of OxAAAA is qqo=. 


table table_key column_name old_value new_value 


usr idu=1 fname NULL Jack 
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event type table table key column name old value new value 


1 usr idu=1 Iname NULL Frost 


1 usr idu=1 photo NULL qqo= 


The XML generated by the Publisher is as follows: 


<add class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<add-attr attr-name="fname"> 
<value type="string">Jack</value> 
</add-attr> 
<add-attr attr-name="lname"> 
<value type="string">Frost</value> 
</add-attr> 
<add-attr attr-name="photo"> 
<value type="octet">qqo=</value> 
</add-attr> 
</add> 


2. Update Field 


The following table shows the contents of the event log table after the row in table usr has 
been updated. The values for column photo has been Base64-encoded. The Base64-encoded 
equivalent of OxBBBB is u7s=. 


event_type table table_key column_name old_value new_value 
2 usr idu=1 fname Jack John 

2 usr idu=1 Iname Frost Doe 

2 usr idu=1 photo qqo= u7s= 


The XML generated by the Publisher is as follows: 


<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr attr-name="fname"> 
<remove-value> 
<value type="string">Jack</value> 
</remove-value> 
<add-value> 
<value type="string">John</value> 
</add-value> 
</modify-attr> 
<modify-attr attr-name="lname"> 
<remove-value> 
<value type="string">Frost</value> 
</remove-value> 
<add-value> 
<value type="string">Doe</value> 
</add-value> 
</modify-attr> 
<modify-attr attr-name="photo"> 
<remove-value> 
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<value type="octet">qqo=</value> 
</remove-value> 
<add-value> 
<value type="octet">u7s=</value> 
</add-value> 
</modify-attr> 
</modify> 


3. Update Field (Remove-All-Values) 


The following table shows the contents of the event log table after the row in table usr has 
been updated. The value for column photo has been Base64-encoded. 


event_type table table_key column_name old_value new_value 
3 usr idu=1 fname Jack John 

3 usr idu=1 Iname Frost Doe 

3 usr idu=1 photo qqo= u7s= 


The XML generated by the Publisher is as follows: 


<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr attr-name="fname"> 
<remove-all-values/> 
<add-value> 
<value type="string">John</value> 
</add-value> 
</modify-attr> 
<modify-attr attr-name="lname"> 
<remove-all-values/> 
<add-value> 
<value type="string">Doe</value> 
</add-value> 
</modify-attr> 
<modify-attr attr-name="photo"> 
<remove-all-values/> 
<add-value> 
<value type="octet">u7s=</value> 
</add-value> 
</modify-attr> 
</modify> 


. Delete Row 


The table below shows the contents of the event log table after the row in table usr has been 
deleted. 


event type table table key column name old value new value 


4 usr idu=1 NULL NULL NULL 


The XML generated by the Publisher would be: 


<delete class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
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</association> 
</delete> 


. Insert Row (Query-Back) 


The following table shows the contents of the event log table after a new row is inserted into 
table usr. 


event type table table key column name old value new value 


5 usr idu=1 NULL NULL NULL 


The XML generated by the Publisher is listed below. The values reflect the current contents 
of table usr, not the initial contents. 


<add class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<add-attr attr-name="fname"> 
<value type="string">John</value> 
</add-attr> 
<add-attr attr-name="lname"> 
<value type="string">Doe</value> 
</add-attr> 
<add-attr attr-name="photo"> 
<value type="octet">u7s=</value> 
</add-attr> 
</add> 


. Update Row (Query-Back) 


The table below shows the contents of the event log table after the row in table usr has been 
updated. 


event type table table key column name old value new value 


6 usr idu=1 NULL NULL NULL 


The XML generated by the Publisher is listed below. The values reflect the current contents 
of table usr, not the initial contents. 


<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr attr-name="fname"> 
<remove-all-values/> 
<add-value> 
<value type="string">John</value> 
</add-value> 
</modify-attr> 
<modi fy-attr attr-name="lname"> 
<remove-all-values/> 
<add-value> 
<value type="string">Doe</value> 
</add-value> 
</modify-attr> 
<modi fy-attr attr-name="photo"> 
<remove-all-values/> 
<add-value> 
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<value type="octet">u7s=</value> 
</add-value> 
</modify-attr> 
</modify> 


7. Insert Field (Query-Back) 


The following table shows the contents of the event log table after a new row is inserted into 
table usr. Old and new values are omitted because they are not used. 


event_type table table_key column_name old_value new_value 
7 usr idu=1 fname NULL NULL 
7 usr idu=1 Iname NULL NULL 
7 usr idu=1 photo NULL NULL 


The XML generated by the Publisher is listed below. The values reflect the current contents 
of table usr, not the initial contents. 


<add class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<add-attr attr-name="fname"> 
<value type="string">John</value> 
</add-attr> 
<add-attr attr-name="lname"> 
<value type="string">Doe</value> 
</add-attr> 
<add-attr attr-name="photo"> 
<value type="octet">u7s=</value> 
</add-attr> 
</add> 


8. Update Field (Query-Back) 


The following table shows the contents of the event log table after the row in table usr has 
been updated. Old and new values are omitted because they are not used. 


event_type table table_key column_name old_value new_value 
8 usr idu=1 fname NULL NULL 
8 usr idu=1 Iname NULL NULL 
8 usr idu=1 photo NULL NULL 


The XML generated by the Publisher is listed below. The values reflect the current contents 
of table usr, not the inital contents. 


<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr attr-name="fname"> 
<remove-all-values/> 
<add-value> 
<value type="string">John</value> 
</add-value> 
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</modify-attr> 
<modify-attr attr-name="lname"> 
<remove-all-values/> 
<add-value> 
<value type="string">Doe</value> 
</add-value> 
</modify-attr> 
<modify-attr attr-name="photo"> 
<remove-all-values/> 
<add-value> 
<value type="octet">u7s=</value> 
</add-value> 
</modify-attr> 
</modify> 


Embedding SQL Statements in XDS Events 


The following section includes information to help you embed SQL in XDS events. 


All examples reference table usr below. The primary key generation method used to obtain 
primary key values is irrelevant for purposes of the examples in this section. 


CREATE TABLE usr 
( 


idu INTEGER NOT NULL, 
fname VARCHAR2 (64), 
lanem VARCHAR2 (64), 


CONSTRAINT pk_usr_idu PRIMARY KEY (idu) 


y; 


You can use embedded SQL in XDS events. In the same way that you can install database triggers 
on a table and cause side effects in a database, embedded SQL in XDS events acts as a virtual 
trigger with similar capabilities. 


SQL is embedded in XDS events through the <jdbc: statement> and <jdbc:sql> elements. 
The <jdbc:statement> element can contain one or more <jdbc : sq1> elements. 


NOTE: The namespace prefix jdbc used throughout this section is implicitly bound to the namespace 
urn:dirxml : jdbc when referenced outside of an XML document. 


The following XML example shows an embedded SQL statement. 


<input xmlns: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement> 
<jdbc:sql> UPDATE indirect.usr SET fname = ’ John’ 
</jdbc:sql> 
</jdbc: statement > 
</input> 


IMPORTANT: You should use namespace-prefixed elements and attributes to embed SQL (otherwise, the 
driver will not recognize them). In the above example, the namespace is urn:dirxml:jdbc. The prefix is the 
identifier to the right of the xmins identifier. In the above example, the prefix is jdbc. In practice, the prefix can 
be whatever you want it to be as long as is is bound to the correct namespace. 
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Because the Subscriber resolves <add> events to one or more INSERT statements, the XML 
shown above resolves to: 


SET AUTOCOMMIT OFF 

INSERT INTO indirect.usr(lname) VALUES ("Doe"); 
COMMIT; --explicit commit 

UPDATE indirect.usr SET fname = 'John'; 
COMMIT; --explicit commit 


Variable Substitution 


Rather than require you to parse field values from an association, the Subscriber supports variable 
substitution in embedded SQL statements. For example: 


<input xmlns:jdbc="urn:dirxml:jdbe"> 
<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr name="lname"> 
<add-value> 
<value>DoeRaeMe</value> 
</add-value> 
</modify-attr> 
</modi fy> 
<jdbc:statement> 
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE 
idu = {$idu}</jdbc:sql> 
</jdbc:statement> 
</input> 


Variable placeholders must adhere to the XSLT attribute value template syntax: { $field-name} 
and the association element must precede the <jdbc:statement> element in the XDS 
document or must be present as a child of the <jdbc: statement> element. The field-name 
variable must refer to one of the naming RDN attribute names in the association value. In the above 
example, there is only one naming attribute, idu. 


An <add> event is the only event where an association element is not required to precede 
embedded SQL statements with variable substitution because the association has not been created 
yet. Additionally, any embedded SQL statements using variable substitution must follow, not 
precede, the <add> event. For example: 


<input xmlins: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement> 
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE 
idu = ($idu)</jdbc:sql> 
</jdbc:statement> 
</input> 


In order prevent tracing of sensitive information, you can use {$$password} to refer to the 
contents of the immediately preceding <password> element within the same document. 


<input xmins: jdbc="urn:dirxml: jdbc"> 


<add class-name="usr"> 
<password>Doe($idu)</password> 
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<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement> 
<jdbc:sql>CREATE USER Doe IDENTIFIED BY 
{$Spassword}</jdbc:sql> 
</jdbc:statement> 
</input> 


Furthermore, you can also refer to the driver’s database authentication password specified by 
parameter “Application Password” on page 37 as ($$Sdriver-password). 


Statement Placement 


In the same way that database triggers can fire before or after a triggering statement, embedded 
SQL can be positioned before or after the triggering XDS event. The following examples show 
how you could embed SQL before or after an XDS event. 


Virtual Before Trigger 


<input xmlns:jdbc"urn:dirxml:jdbe"> 
<jdbc:statement> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<jdbc:sql>UPDATE indirect.usr SET fname = ‘John’ WHERE 
idu = {$idu}</JDBC: SQL> 
</jdbc:statement> 
<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr name="lname"> 
<remove-all-values/> 
<add-value> 
<value>Doe</value> 
</add-value> 
</modify-attr> 
</modi fy> 
</input> 


This XML resolves to: 


SET AUTOCOMMIT OFF 

UPDATE indirect.usr SET fname = ’John’ WHERE idu = 1; 
COMMIT; --explicit commit 
UPDATE indirect.usr SET lname = ’Doe’ WHERE idu 
COMMIT; --explicit commit 
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Virtual After Trigger 


<input xmlns:jdbc"urn:dirxml:jdbc"> 
<modify class-name="usr"> 
<association>idu=1,table=usr, schema=indirect 
</association> 
<modify-attr name="lname"> 
<remove-all-values/> 
<add-value> 
<value>Doe</value> 
</add-value> 
</modify-attr> 
</modi fy> 
<3jdbc : statement> 
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<jdbc:sql>UPDATE indirect.usr SET fname = ’John’ WHERE 
idu = {$idu}</Jdbc:sql> 
</jdbc:statement> 
</input> 


This XML resolves to: 


SET AUTOCOMMIT OFF 

UPDATE indirect.usr SET lname = 'Doe” WHERE idu = 1; 
COMMIT; --explicit commit 
UPDATE indirect.usr SET fname = ’John’ WHERE idu = 1; 
COMMIT; --explicit commit 


Manual vs. Automatic Transactions 


You can manually group embedded SQL and XDS events using these two custom attributes: 
jdbc:transaction-type and jdbc: transaction-id. 


jdbc:transaction-type 


This attribute has two values: manual and auto. By default, most XDS events of interest 
(<add>, <modify> and <delete>) are implicitly set to the manual transaction type. The manual 
setting enables XDS events to resolve to a transaction consisting of one or more SQL statement. 


Embedded SQL events are set to auto transaction type by default because some SQL statements, 
such as DDL statements, cannot usually be included in a manual transaction. 


<input xmlns:jdbc="urn:dirxml:jdbe"> 
<add class-name="usr" jdbc:transaction-type="auto"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<3jdbc: statement> 
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' WHERE 
idu = {$idu}</jdbc:sql> 
</jdbc:statement> 
</input> 


This XML resolves to: 


SET AUTOCOMMIT ON 

INSERT INTO indirect.usr(lname) VALUES ('Doe"'); 

-- implicit commit 

UPDATE indirect.usr SET fname = 'John' WHERE idu = 1; 
-- implicit commit 


jdbc:transaction-id 


This attribute is ignored by the Subscriber unless the element's jdbc: transaction-type 
attribute value defaults to or is explicitly set to manual. The following XML shows an example 
of a manual transaction: 


<input xmlins: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr" jdbc:transaction-id="0"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
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<jdbc:statement jdbc:transaction-type="manual" 
jdbc:transaction-id="0"> 
<jdbc:sq1>UPDATE indirect.usr SET fname = 'John' WHERE 
idu = {$idu}</jdbc:sql> 
</jdbc:statement> 
</input> 


This XML resolves to: 


SET AUTOCOMMIT OFF 


INSERT INTO indirect.usr(lname) VALUES (*Doe'); 
UPDATE indirect.usr SET fname = 'John' WHERE idu = 1; 
COMMIT; -- explicit commit 


Transaction Isolation Level 


In addition to grouping statements, transactions are used to preserve the integrity of data in a 
database. Transactions can lock data in order to prevent concurrent access or modification. How 
locks are set is determined by the isolation level of a transaction. Usually, the default isolation 
level used by the driver is sufficient and should not be altered. 


The custom attribute jdbc:isolation-level allows you to adjust the isolation transaction 
level if necessary. There are five possible values defined in the java.sql.Connection (http:// 
java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.html) interface: 


* none 

* read uncommitted 
* read committed 

* repeatable read 


* serializable 


This product’s default transaction isolation level is read committed unless overridden by a 
descriptor file. In the case of a manual transaction, the jdbc:isolation-level attribute 
should be placed on the first element in the transaction. This attribute is ignored on subsequent 
elements. For example: 


<input xmins: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr" jdbc:transaction-id="0" 
jdbc:isolation-level="serializable"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement jdbc:transaction-type="manual" 
jdbc:transaction-id="0"> 
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' 
WHERE idu = {$idu}</jdbc:sql> 
</jdbc:statement> 
</input> 


This XML resolves to: 


SET AUTOCOMMIT OFF 
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE 


INSERT INTO indirect.usr(lname) VALUES ('Doe'); 
UPDATE indirect.usr SET fname = 'John' WHERE idu = 1; 
COMMIT; -- explicit commit 
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Statement Type 


The Subscriber executes embedded SQL statements, but it doesn’t understand them. The JDBC 1 
interface defines several methods for executing different types of SQL statements. The following 
table contains these methods: 


Statement Type Method Executed 

SELECT java.sql.Statement.executeQuery(String query):java.sql.ResultSet 
INSERT java.sql.Statement.executeUpdate(String update):int 

UPDATE java.sql.Statement.executeUpdate(String update):int 

DELETE java.sql.Statement.executeUpdate(String update):int 

CALL or EXECUTE java.sql.Statement.execute(String sql):boolean 

SELECT 

INSERT 

UPDATE 

DELETE 


The simplest solution is to map all SQL statements to the 

java.sql.Statement .execute (String sql) :boolean method. By default, this is the 
method the Subscriber uses. Some third-party drivers, particularly Oracle’s JDBC drivers, 
incorrectly implement the methods used to determine the number of result sets generated by this 
method. Consequently, the driver can get caught in an infinite loop leading to high CPU utilization. 
To circumvent this problem, the jdbc : type attribute can be used on any <jdbc: statement> 
element to map the SQL statements contained in it to the 

java.sql.Statement .executeQuery (String query) :java.sql.ResultSet or 
java.sql.Statement.executeUpdate (String update) : int methods instead of the 
default method. 


The jdbc: type attribute has two values: update and query. The value should be set to 
update for INSERT, UPDATE, or DELETE statements and query for SELECT statements. In the 
absence of this attribute, the driver maps all SQL statements to the default method. If placed on 
any element other than <jdbc:statement>, this attribute is ignored. 


We recommend that you place the jdbc: type="query" attribute value on all SELECT 
statements, the jdbc: type="update" attribute value on all INSERT, UPDATE and DELETE 
statements and no attribute value on stored procedure/function calls. 


The following XML shows an example of the jdbc:type attribute: 


<input xmlns:jdbc="urn:dirxml:jdbe"> 
<add class-name="usr"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement jdbc:type="update"> 
<jdbc:sql>UPDATE indirect.usr SET fname = 'John' 
WHERE idu = {S$idu}</jdbc:sql> 
</jdbc:statement> 
</input> 
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SQL Queries 


In order to fully support the query capabilities of a database and avoid the difficulty of translating 
native SQL queries into an XDS format, the driver supports native SQL query processing. Select 
statements can be embedded in XDS documents in exactly the same way as any other SQL 
statement. 


For example, assume that the contents of table usr are as follows: 


idu fname Iname 


1 John Doe 


The XML document below would result in an output document containing a single result set. 


<input xmlns:jdbc="urn:dirxml:jdbe"> 
<jdbc:statement jdbc:type="query"> 
<jdbc:sql>SELECT * FROM indirect .usr</jdbc: sql> 
</jdbc: statement > 
</input> 


<output xmlns:jdbc="urn:dirxml:jdbc"> 
<jdbc:result-set jdbc:number-of-rows="1"> 
<jdbc:row jdbc:number="1"> 
<3jdbc: column jdbc:name="idu" 
jdbc:position="1" 
jdbc :type="java.sql.Types .BIGINT 
<jdbc : value>1</jdbc: value> 
</jdbc: column> 
<jdbc:column jdbc:name="fname" 
jdbc: position="2" 
jdbc: type="java.sql.Types . VARCHAR> 
<jdbc : value>John</ jdbc: value> 
</ jdbc :column> 
<jdbc:column jdbc:name="lname" 
jdbc: position="3" 
jdbc: type="java.sql.Types . VARCHAR> 
<jdbc: value>Doe</ jdbc: value> 
</jdbc: column> 
</jdbc: row> 
</ jdbc: result-set> 
<status level="success"/> 
</output> 


SQL queries always produce a single <jdbc: result-set> element whether or not the result 
set contains any rows. If the result set is empty, the jdbc : number-of-rows attribute is set to 
Zero. 


More than one query can be embedded in a document. SQL queries do not require that the 
referenced tables/views are visible to the driver; XDS queries do. 


Data Definition Language (DDL) Statements 


It is generally not possible to run a Data Definition Language (DDL) statement in a database 
trigger because most databases do not allow mixed DML and DDL transactions. Although virtual 
triggers do not overcome this transactional limitation, they do allow DDL statements to be 
executed as a side-effect of an XDS event. For example: 
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<input xmlns:jdbc="urn:dirxml:jdbc"> 
<add class-name="usr"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement> 
<jdbc:sql>CREATE USER indirect IDENTIFIED BY novell 
</jdbc: sql> 
</jdbc: statement > 
</input> 


This XML resolves to: 


SET AUTOCOMMIT OFF 

INSERT INTO indirect.usr(lname) VALUES ('Doe'); 
COMMIT; -- explicit commit 

SET AUTOCOMMIT ON 

CREATE USER indirect IDENTIFIED BY novell; 

-- implicit commit 


Using the jdbc:transaction-idand jdbc:transaction-type attributes to group DML 
and DDL statements into a single transaction would result in the transaction being rolled back on 
most databases. Because DDL statements are generally executed as separate transactions, it is 
possible that the insert statement in the example above might succeed and the create user statement 
might roll back. It is not possible, however, that the insert statement fail and the create user 
statement succeed. The Subscriber stops executing chained transactions at the point where the first 
transaction is rolled back. 


Logical Operations 


Because it is not generally possible to mix DML and DDL statements in a single transaction, a 
single event can consist of one or more transactions. The jdbc: op-idand jdbc: op-type can 
be used to group multiple transactions together into a single logical operation. When so grouped, 
all members of the operation are handled as a single unit with regard to status. If one member has 
an error, all members return the same status level. Similarly, all members share the same status 


type. 


<input xmlins: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr" jdbc: op-id="0" 
jdbc: op-type="password-set-operation"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
<password>Doe($idu)</password> 
</add> 
<3jdbc: statement jdbc:op-id="0"> 
<jdbc:sql>CREATE USER Doe IDENTIFIED BY ($$password) 
</jdbe:sql> 
</jdbc:statement> 
</input> 


The jdbc: op-type attribute is ignored on all elements except the first element in a logical 
operation. 
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Best Practices 


For performance reasons, it is better to call a single stored procedure/function that contains 


multiple SQL statements than to embed multiple statements in an XDS document. For example: 


<input xmlns:jdbc="urn:dirxml:jdbe"> 
<add class-name="usr"> 
<add-attr name="fname"> 
<value>John</value> 
</add-attr> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc: statement > 
<jdbc:sql>CALL PROCEDURE set_name(’John’, ‘Doe’ )</jdbc:sql> 
</jdbc: statement> 
</input> 


Is preferred to: 


<input xmlns: jdbc="urn:dirxml: jdbc"> 
<add class-name="usr"> 
<add-attr name="lname"> 
<value>Doe</value> 
</add-attr> 
</add> 
<jdbc:statement> 
<jdbc:sql>UPDATE indirect.usr SET fname = ’ John’ 
WHERE idu = ($idu)</jdbc:sql> 
</jdbc: statement> 
<jdbc : statement> 
<jdbc:sql>UPDATE indirect.usr SET lname = ’Doe’ 
WHERE idu = ($idu)</jdbc:sql> 
</jdbc: statement> 
</input> 


The sytnax used to call stored procedures/functions varies by database. For additional 
information, see “Stored Procedure and Function JDBC Call Syntaxes” on page 113. 
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Third-Party JDBC Drivers 


In this section, you will find information about third-party JDBC drivers. 
+ “Third-Party JDBC Driver Interoperability” on page 97 
+ “JDBC Driver Types” on page 97 
+ “Supported Third-Party JDBC Drivers” on page 98 
+ “Using Unsupported Third-Party JDBC Drivers” on page 109 


+ “Security Issues” on page 109 


Third-Party JDBC Driver Interoperability 


This product is designed to interoperate with a specific set of third-party JDBC drivers, instead of 
a specific set of databases. In fact, the third-party JDBC driver, not the database, is the primary 
determinant of whether this product works against any given database. As a general rule, if this 
product interoperates well with a given third-party JDBC driver, it will interoperate well with 
databases and database versions the third-party driver supports. 


We strongly recommend that you use the third-party JDBC drivers supplied by major enterprise 
database vendors whenever possible, such as those listed in this section. They are usually free, 
mature, and known to interoperate well with this product and the databases they target. You can 
use other third-party drivers, but they are not supported by Novell. 


In general, most third-party drivers are backward compatible. However, even if they are generally 
backward compatible, they not generally forward compatible. Anytime a database server is 
upgraded, the third-party driver used with this product should probably be updated as well. 


Also, as a general rule, we recommend that you use the latest version of a third-party driver unless 
otherwise noted. 


JDBC Driver Types 


There are four types of JDBC drivers: 


Type 1 


A third-party JDBC driver that is partially Java and communicates indirectly with a database 
server through a native ODBC driver. Type 1 drivers serve as a JOBC-ODBC bridge. Sun provides 
a JDBC-ODBC bridge driver for experimental use and for situations when no other type of third- 
party JDBC driver is available. 
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Type 2 


A third-party JDBC driver that is part Java and communicates indirectly with a database server 
through its native client APIs. 


Type 3 


A third-party JDBC driver that is pure Java and communicates indirectly with a database server 
through a middleware server. 


Type 4 


A third-party JDBC driver that is pure Java and communicates directly with a database server. 


Which Type To Use? 


Type 3 and 4 drivers are generally more stable than type 1 and 2 drivers. Type 1 and 2 drivers are 
generally faster than type 3 and 4 drivers. Type 2 and 3 drivers are generally more secure than type 
1 and 4 drivers. 


Because IDM uses a directory as its datastore, and because databases are usually significantly 
faster than directories, performance isn’t of primary concern. Stability, however, is an issue. For 
this reason, we recommend that you use a type 3 or 4 third-party JDBC driver whenever possible. 


IMPORTANT: If you choose to use a type 1 or type 2 driver with this product, you must use the remote loader 
to ensure the integrity of the directory process. 


Supported Third-Party JDBC Drivers 


+ “BEA Weblogic jDriver for Microsoft SQL Server” on page 100 

+ “IBM DB2 Universal Database JDBC Drivers” on page 101 

+ “Microsoft SQL Server 2000 Driver for JDBC” on page 104 

+ “MySQL Connector/J JDBC Driver” on page 105 

+ “Oracle Thin Client JDBC Drivers” on page 106 

+ “PostgreSQL JDBC Driver” on page 107 

+ “Sybase Adaptive Server Enterprise JConnect JDBC Driver” on page 108 
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The following table is a summary of third-party JDBC driver features: 


Driver Supports Encrypted Transport? Supports Retrieval of Auto-Generated Keys? 


BEA Weblogic ¡Driver No No 
IBM DB2 UDB Type No No 
3 
IBM DB2 UDB Type No No 
4 
Informix No No 
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Driver Supports Encrypted Transport? Supports Retrieval of Auto-Generated Keys? 


Microsoft 2000 No No 
MySQL Connector/J Yes Yes 
Oracle Client Thin Yes No 
PostgreSQL Yes* No 
Sybase ¡Connect Yes No 


* For versions JDBC 3 (Java 1.4) and later. 


JDBC URL Syntaxes 


The following table lists URL syntaxes for supported third-party JDBC drivers: 


Third-Party JDBC Driver JDBC URL Syntax 
Oracle Thin Client jdbc:oracle:thin:@jp-address:1521:sid 
IBM DB2 UDB Type 3 jdbc:db2://ip-address:6789/database-name 


IBM DB2 UDB Type 4, Universal jdbc:db2://ip-address:50000/database-name 
BEA Weblogic* jDriver jdbc:weblogic:mssqlserver4:database-name@ip-address:1433 


Microsoft SQL Server jdbc:microsoft:sqlserver://ip-address-or-dns- 
name:1433;DatabaseName=database-name 


Sybase jConnect jdbc:sybase:Tds:ip-address:2048/database-name 
MySQL Connector/J jdbe:mysaql://ip-address:3306/database-name 
Informix jdbc:informix-sqli://ip-address: 1526/database- 


name: informixserver=server-id 


PostgreSQL jdbc:postgresal://ip-address:5432/database-name 


JDBC Driver Class Names 


The following table lists the fully-qualified Java class names of supported third-party JDBC 


drivers: 
Third-party JDBC Driver Class Name 
BEA Weblogic jDriver weblogic.jdbc.mssqlserver4. Driver 
IBM DB2 UDB Type 3 COM.ibm.db2.jdbc.net.DB2Driver 
IBM DB2 UDB Type 4, Universal com.ibm.db2.jcc.DB2Driver 
Informix com. informix.jdbc.lfxDriver 


Third-Party JDBC Drivers 99 


Third-party JDBC Driver 
Microsoft 2000 

MySQL Connector/J 
Oracle Thin Client 
PostgreSQL 


Sybase jConnect 5.5 


Class Name 
com.microsoft.jdbc.sqlserver.SQLServerDriver 
org.gjt.mm.mysaql.Driver 
oracle.jdbc.driver.OracleDriver 
org.postgresql.Driver 


com.sybase.jdbc2.jdbc.SybDriver 


BEA Weblogic ¡Driver for Microsoft SQL Server 
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Supported Database Version: 


Microsoft SQL Server 6.5, 7.x, 8.x (2000) 


Class Name weblogic.jdbc.mssqlserver4.Driver 
Type 4 
URL Syntax jdbc:weblogic:mssqlserver4:database-name@ip-address: 1433 


Download Instructions 


Register for free and download the latest version of Weblogic server. 
Run the installer. The weblogic.jar file is installed in the install-dir/ 
server/lib directory. 


BEA Download Center (http://commerce.bea.com/ 
showallversions.jsp?family=WLS) 


Filename 


weblogic.jar 


Documentation URLs 


jDriver Documentation (http://e-docs.bea.com/wls/docs81/ 
mssqlserver4/) 


NOTE: This driver is included in the supported third-party driver listing to provide JDBC access to Microsoft 


SQL server 7 because Microsoft's 


Compatibility 


driver only supports version 8 (2000). 


This driver is backward compatible. Database server and driver updates are infrequent. 


Security 


This driver does not support encrypted transport. 


Known Issues 


¢ This driver is not free. It must be purchased and properly licensed. 


+ Association values that contain UNIQUEIDENTIFIER columns are inconsistent between 


driver versions. 


Earlier versions of this driver returned a non-standard java.sql. Types (http://java.sun.com/ 
j2se/1.5.0/docs/api/java/sql/Types.html) value for native UNIQUEIDENTIFIER columns. To 
compensate, this product mapped that non-standard type to the standard type 
java.sql.Types.BINARY (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Types.html) since 
1t best mirrored the native database type -- a 16 byte value. This mapping results in a Base64- 


encoded association value. 
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Later versions of this driver return a standard type java.sql. CHAR 


(http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Types.html). This mapping results in a non- 
Base64-encoded association value, effectively invalidating all associations generated using 
older versions of this driver. This change effectively breaks backward compatibility. The best 
solution to this problem is to continue using the older version of this driver. If you must 
upgrade, you’ll have to remove all invalidated associations and reassociate all previously- 
associated objects. 


+ This driver throws a java.lang.Illegal MonitorStateException (http://java.sun.com/j2se/1.5.0/ 
docs/api/java/lang/IllegalMonitorStateException.html) when method 
java.sql.Connection.getConnection (String url, String username, 
String password) is called on AIX. 


IBM DB2 Universal Database JDBC Drivers 


Type 3 


Supported Database Versions: 7.x 


Class Name: COM.ibm.db2.jdbc.net.DB2Driver 

Type 3 

URL Syntax: jdbc:db2://ip-address:6789/database-name 
Download Instructions: Copy the file from the database server. 


file:///database-installation-directory/java 


File Name: db2java.zip 
Documentation URLs: DB2 Information Center (http://publib.boulder.ibm.com/infocenter/ 
db2v7luw) 


JDBC Programming (http://publib.boulder.ibm.com/infocenter/ 
db2v7luw/index.jsp?topic=/com.ibm.db2v7.doc/db2a0/ 
db2a0159.htm) 


IMPORTANT: The type 3 driver is deprecated for version 8. 


Compatibility 


This driver can best be characterized as version-hypersensitive. It is not compatible across major 
or minor versions of DB2, including FixPacks. For this reason, we recommend that you use the 
file installed on the database server. 


IMPORTANT: This driver must be updated on the IDM/Remote Loader server every time the target database 
is updated, even if only at the FixPack level. 


Security 
This driver does not support encrypted transport. 
Known Issues 


+ A version mismatch usually results in connectivity-related failures. 


The most common problem experienced with this driver is because of a driver/database 
version mismatch. The symptom of a version mismatch is connectivity-related failures such 
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as "CLI0601E Invalid statement handle or statement is closed." To remedy the problem, 
overwrite the db2java. zip file on the IDM/Remote Loader server with the version 
installed on the database server. 


+ It's very difficult to diagnose and remedy Java-related errors on the database server. 


There are numerous error conditions and error-codes that can arise when attempting to install 
and execute user-defined stored procedures and functions written in Java. Diagnosing them 
can prove time intensive and frustrating. There is a log file named db2diag. log on the 
database server that can often provide additional debugging information. In addition, all error 
codes are documented and available online. 


Type 4, Universal Drivers 
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Supported Database Versions 


8.x 


Class Name com.ibm.db2.jcc. DB2Driver 
Type 4 
URL Syntax jdbc:db2://ip-address:50000/database-name 


Download Instructions 


Download as part of the latest FixPack (recommended). 
IBM Support & Downloads (http://www.ibm.com/support/us/) 
or 

Copy the file from the database server. 


file:///database-installation-directory/java 


Filename 


db2jcc.jar, db2jcc_license_cu.jar, db2jcc_javax.jar (optional) 


Documentation URLs 


DB2 Information Center (http://publib.boulder.ibm.com/infocenter/ 
db2help) 


DB2 Universal JDBC Driver (http://publib.boulder.ibm.com/infocenter/ 
db2help/index.jsp?topic=/com.ibm.db2.udb.doc/ad/t0010264.htm) 


Security under the DB2 Universal JDBC Driver (http:// 
publib.boulder.ibm.com/infocenter/db2help/index.jsp?topic=/ 
com.ibm.db2.udb.doc/ad/cjvjcsec.htm) 


NOTE: Unlike the type 3 driver, only a minimal set of error codes have yet been defined, which inhibits this 
product's ability to distinguish between connectivity, retry, authentication, and fatal error conditions. 


Compatibility 


This driver is backward compatible, although it doesn’t work with database version 7. Database 
server updates are frequent. Driver updates are infrequent. 


Security 


This driver supports a variety of authentication security mechanisms but does not support 


encrypted transport. 


Known Issues 


¢ It’s very difficult to diagnose and remedy Java-related errors on the database server. 
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There are numerous error conditions and error codes that can arise when attempting to install 
and execute user-defined stored procedures and functions written in Java. Diagnosing these 
can prove time intensive and frustrating. There is a log file named db2diag.log on the 
database server that can often provide additional debugging information. In addition, all error 
codes are documented and available online. 


Informix JDBC Driver 


Supported Database Versions Dynamic Server 7.x, 9.x 


Class Name com.informix.jdbc.!fxDriver 

Type 4 

URL Syntax jdbc:informix-sqli://ip-address: 1526/database- 
name: informixserver=server-id 

Download Instructions Download URL (http://www-306.ibm.com/software/data/informix/ 
tools/jdbc) 

Filenames ifxjdbc.jar, ifxjdbcx.jar (optional) 

Documentation URLs Informix Information Center (http://publib.boulder.ibm.com/infocenter/ 
ids9help/index.jsp) 


Informix JDBC Driver (http://www-306.ibm.com/software/data/ 
informix/pubs/library/jdbc_2.html) 


Compatibility 
This driver is backward compatible. Database server updates and driver updates are infrequent. 


Security 


This driver does not support encrypted transport. 


Required Parameter Settings for ANSI-Compliant Databases 


The following table lists driver parameters that must be explicitly set for this product to 
interoperate with this driver against ANSI-compliant databases. 


Display Name Tag Name Value 
Supports schemas in metadata retrieval? | supports-schemas-in-metadata-retrieval false 
Force username case: force-username-case upper 


Dynamic Parameter Defaults 


The following table lists driver compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 


Function return method: function-return-method result set 
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Known Issues 


+ Schema names cannot be used to retrieve metadata against an ANSI-compliant database. The 
driver compatibility parameter "Supports schemas in metadata retrieval?” on page 50 should 
be set to Boolean False. 


The database objects available for metadata retrieval are those visible to the database user who 
authenticated to the database. Because schema qualifiers cannot be used to identify database 
objects, the database authentication user should only be given SELECT privileges on objects 
being synchronized to avoid naming collisions (such as, ownerl.tablel, owner2.table1). 


+ Uppercase usernames are required when used against ANSI-compliant databases. The driver 
compatibility parameter "Force username case” on page 49 should be set to upper. 


Microsoft SQL Server 2000 Driver for JDBC 


Supported Database Versions: 8 (2000) 


Class Name com.microsoft.jdbc.sqlserver.SQLServerDriver 
Type 4 
URL Syntax jdbc:microsoft:sqlserver://ip-address-or-dns- 


name:1433;DatabaseName=database-name 


Download Instructions Microsoft JDBC Downloads (http://www.microsoft.com/downloads/ 
results.aspx?sortCriteria=date&OSID=&productID=&CategorylD=&fr 
eetext=jdbc&DisplayLang=en&DisplayEnglishAlso=) 


Filenames msbase.jar, mssqlserver.jar, msutil.jar 


Compatibility 


This driver is backward compatible, although it doesn’t work with database version 7. Database 
server and driver updates are infrequent. 


Security 


This driver does not support encrypted transport. 


URL Properties 
URL properties are delimited using a ‘;’ character. 


The following table lists some important URL properties for this driver. 


Property Legal Values 

SelectMethod direct 
The default value; doesn’t allow for multiple active statements on a single connection 
cursor 


Allows for multiple active statements on a single connection 
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Dynamic Parameter Defaults 


The following table lists driver compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 


Reuse Statements? reuse-statements false 


Known Issues 
+ Can't start manual transaction because of cloned connections. 


The most common problem experienced with this driver is because of an implementation 
anomaly that doesn't allow concurrent statements to be active on the same connection. Unlike 
other third-party implementations, only one java.sql.Statement (http://java.sun.com/j2se/ 
1.5.0/docs/api/java/sql/Statement.html) object can be active at a time on a given connection. 
If an attempt is made to use more than one statement object, the following error is issued: 
“Can't start manual transaction mode because there are cloned connections.” This can only 
occur if driver compatibility parameter “Reuse statements?” on page 46 is set to Boolean 
True. As a best practice, never explicitly set this parameter and defer to the dynamic default 
value. 


An alternative is to place the delimited property ; SelectMethod=cursor at the end of the 
URL string. For additional information on this issue, consult these support articles by Data 
Direct (http://knowledgebase.datadirect.com/kbase.nsf/SupportLink+Online/ 
30096?OpenDocument) and Microsoft (http://support.microsoft.com/ 
default.aspx?scid=kb%3 Ben-us%3B3 13181). 


* 


Association values that contain UNIQUEIDENTIFIER columns are inconsistent between 
driver versions. 


Earlier versions of this driver returned a nonstandard java.sql.Types (http://java.sun.com/j2se/ 
1.5.0/docs/api/java/sql/Types.html) value for native UNIQUEIDENTIFIER columns. To 
compensate, this product mapped that non-standard type to the standard type 
java.sql.Types.BINARY (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Types.html) 
because it best mirrored the native database type -- a 16 byte value. This mapping results in a 
Base64-encoded association value. Later versions of this driver return a standard type 
java.sql. CHAR (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Types.html). This mapping 
results in a non-Base64-encoded association value, effectively invalidating all associations 
generated using older versions of this driver. This change effectively breaks backward 
compatibility. The best solution to this problem is to continue using the older version of this 
driver. If you must upgrade, you”1l have to remove all invalidated associations and reassociate 
all previously-associated objects. 


MySQL Connector/J JDBC Driver 


Supported Database Versions 3.x, 4.x 


Class Name org.gjt.mm.mysql.Driver 
Type 4 
URL Syntax jdbc:mysadl://ip-address:3306/database-name 
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Download Instructions Download and extract. The jar file is located in the extract-dir/mysql- 
connector-java-version directory. 


MySQL Connector/J (http://www.mysql.com/products/connector/;/) 


Filename mysql-connector-java-version-bin.jar 
Documentation URLs MySQL Connector/J Documentation (http://dev.mysql.com/doc/ 
connector/j/en/) 


Connecting Over SSL (http://dev.mysql.com/doc/connector/j/en/cj- 
ssl-connection.html) 


Compatibility 


This driver is backward compatible. Database server updates are frequent. Driver updates are 
infrequent. 


Security 


This driver supports JSSE (Java Secure Sockets Extension) SSL-encrypted transport. 


Required Parameter Settings for MyISAM Tables 


The following table lists driver parameters that must be set for this product to interoperate with 
this driver against MyISAM tables. 


Display Name Tag Name Value 


Use manual transactions? use-manual-transactions false 


Oracle Thin Client JDBC Drivers 
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Supported Database Versions 8i, 9i, 10g 


Class Name oracle.jdbc.driver.OracleDriver 

Type 4 

URL Syntax jdbc:oracle:thin:@ip-address:1521:sid 
Download Instructions Register for free and download. 


Oracle Technology Network (http://otn.oracle.com/software/tech/ 
java/sqlj_jdbc/content.html) 


1.1 Filenames classes111.zip, nls_charset11.zip (optional) 

1.2-3 Filenames classes12.zip, ocrs12.zip (optional), nls_charset12.zip (optional) 
1.4 Filenames ojdbc14.jar, ocrs12.zip (optional) 

Documentation URLs Oracle Advanced Security (http://www.oracle.com/technology/ 


sample_code/deploy/security/files/secure_thin_driver/readme.html) 
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Compatibility 
This driver is backward compatible. Database server updates and driver updates are infrequent. 


Oracle releases thin client drivers for various JVMs. Even though all of them work with this 
product, we recommend you use the 1.4 version. 


Security 


This driver supports Oracle Advanced Security encrypted transport. 


Dynamic Parameter Defaults 


The following table lists driver compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 


Number of returned result sets: | handle-stmt-results single 


Known Issues 
+ High CPU utilization triggered by execution of embedded SQL statements. 


The most common problem experienced with this driver is high CPU utilitization, because of 
this driver always indicates that more results are available from calls to method 
java.sql.Statement .execute (String stmt) which can lead to an infinite loop 
condition. This condition occurs only if driver compatibility parameter “Number of returned 
result sets” on page 47 other than single, no or one and an embedded SQL statement is 
being executed and the type of statement is not explicitly specified. To avoid the conditions 
necessary to produce high CPU utilization, do not explicitly set this parameter, thereby 
deferring to the dynamic default and always place a jdbc: type attribute on any embedded 
<jdbc:statement> elements. 


NOTE: The jdbc namespace prefix maps to urn:dirxml:jdbc. 


PostgreSQL JDBC Driver 


Supported Database Versions 6.x, 7.x, 8.x 


Class Name org.postgresql.Driver 

Type 4 

URL Syntax jdbc:postgresal://ip-address:5432/database-name 

Download Instructions JDBC Driver Download (http://jdbc.postgresql.org/download.html) 
Documentation URLs JDBC Driver Documentation (http://jdbc.postgresql.org/ 


documentation/docs.html) 


Using SSL (http://jdbc.postgresql.org/documentation/80/ssl.html) 


NOTE: The filename of this driver varies by database version. 
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Compatibility 


The latest builds of this drive are backward compatible through server version 7.2. Database server 
updates and driver updates are frequent. 


Security 


This driver supports SSL-encrypted transport for JDBC 3 driver versions. 


Sybase Adaptive Server Enterprise JConnect JDBC Driver 
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Supported Database Versions Adaptive Server Enterprise 11.x, 12.x 


Class Name com.sybase.jdbc2.jdbc.SybDriver (for jconn2.jar) 
com.sybase.jdbc3.jdbc.SybDriver (for jconn3.jar) 


Type 4 

URL Syntax jdbc:sybase:Tds:ip-address:2048/database-name 

Download Instructions Sybase Downloads (http://www.sybase.com/detail?id=1009796) 
Filenames jconn2.jar or jconn3.jar 

Documentation URLs jConnect Documentation (http://sybooks.sybase.com/onlinebooks/ 


group-jc/jcg0600e/prjdbc) 


Compatibility 


This driver is backward compatible. Database server updates and driver updates are infrequent. 


Security 


This driver supports SSL-encrypted transport. In order to enable SSL encryption, you must specify 
a custom socket implementation via the SYBSOCKET FACTORY connection property. For 
addition information on how to set connection properties, refer to “Connection properties” on 
page 43. 


Connection Properties 


The following table lists some important connection properties for this driver. 


Property Significance 


SYBSOCKET_FACTORY This property can be used to specify the class name of a custom socket 
implementation that supports encrypted transport. 
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Using Unsupported Third-Party JDBC Drivers 


Minimum Third-Party JDBC Driver Requirements 


This product might not interoperate with all third-party JDBC drivers. If you choose to use an 
unsupported third-party JDBC driver, it must meet the following requirements: 


+ It must support required metadata methods. 


Refer to Appendix D, “java.sql.DatabaseMetaData Methods,” on page 137 for a current list 
of the required and optional java.sql.DatabaseMetaData method calls made by this product. 


+ It must support other required JDBC methods. 


Refer to Appendix E, “Utilized JDBC Methods,” on page 139 for a list of required JDBC 
methods used by this product. This list can be used in collaboration with third-party driver 
documentation to identify potential incompatibilities. 


Considerations When Using Other Third-Party JDBC Drivers 


+ Because this product is directly dependent upon third-party JDBC driver implementations, 
bugs in those implementations might cause this product to malfunction. In order to assist you 
in debugging third-party JDBC drivers, this product supports tracing at the JDBC API level 
(level 6) and third-party JDBC driver (level 7) tracing. 


+ Stored procedure or function support is a likely point of failure. 


+ You'll probably need to write a custom driver descriptor file. Specifically, you”ll need to 
categorize error codes and SQL states for the third-party driver you are using. 


Security Issues 


To ensure that a secure connection exists between this product and a third-party driver, we 
recommends that you run this product remotely on the database server and use SSL to encrypt 
communications between the IDM server and database server. 


When this product cannot run remotely, you might want to use a type 2 or type 3 JDBC driver. 
These driver types often facilitate a greater degree of security through middleware servers or client 
APIs unavailable to other JDBC driver types. Some type 4 drivers support encrypted transport, but 
this is the exception rather than the rule. 


Third-Party JDBC Drivers 109 


110 IDM Driver for JDBC Implementation Guide 


Supported Databases 


In this section, you will find useful information about the enterprise-level databases supported by 


this product. 


+ “Database Interoperability” on page 111 
+ "Supported Databases” on page 111 


+ “Database Characteristics” on page 112 


Database Interoperability 


This product is designed to interoperate with a specific set of JDBC driver implementations, 


instead of a specific set of databases. Consequently, the list of supported databases is primarily 
driven by the capabilities of supported third-party JDBC drivers. A secondary factor is testing 


resources. 


Supported Databases 


The following databases/database versions have been tested and are recommended for use with 


this product: 


Database Minor Version 
IBM* DB2 Universal Database (UDB) 7 7.2 or higher 
IBM* DB2 Universal Database (UDB) 8 8.1 or higher 
Informix* Dynamic Server (IDS) 9.40 or higher 


Microsoft SQL Server 7 


7.5, Service Pack 4 or higher 


Microsoft* SQL Server 8 (2000) 


Service Pack 3a or higher 


MySQL* 3 


3.23.50 or higher 


MySQL* 4 


4.1 or higher 


Oracle 8i 


Release 3 (8.1.7) or higher 


Oracle 9i 


Release 2 (9.2.0.1) or higher 


Oracle 10g 


Release 1 (10.0.2.1) or higher 


PostgreSQL 7 


7.4.6 or higher 


Sybase* Adaptive Server Enterprise (ASE) 12 


12.5 or higher 
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You can use this product with other databases/database versions. However, they are not supported 
by Novell. In order to interoperate with this product, a database must: 


+ Support the SQL-92 entry level grammar. 
+ Be JDBC-accessible. 


Database Characteristics 


+ "Database Features” on page 112 

+ "TBM DB2 Universal Database (UDB)” on page 115 
+ “Informix Dynamic Server (IDS)” on page 116 

+ "Microsoft SQL Server” on page 116 

+ “MySQL” on page 117 

+ “Oracle” on page 117 

+ “PosgreSQL” on page 118 


+ “Sybase Adaptive Server Enterprise (ASE)” on page 119 


Database Features 


The following table is a summary of database features: 


Database Schemas Views Identity Sequences Stored Functions Triggers Instead-Of- 
Columns Procedures Triggers 

IBMDB2UDB7 X X X 0 x" X! X 0 
IBMDB2UDB8 X X X 0 x! x" X X 
Informix IDS 9 X X x? 0 x8 X X 0 

MS SQL 7 X X X 0 X 0 X 0 

MS SQL 8 X X X 0 X X X X 
MySQL 4 0 0 x4 0 0 0 0 0 
Oracle 8i, 9i, 10g X X 0 X X X X X 
Postgres 7 Xx X x5 X X Xx x6 x6 
Sybase ASE 12 X X X 0 X 0 X 0 
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1. DB2 natively supports stored procedures/functions written in Java. In order to write 
procedures using the native SQL procedural language, a C compiler must be installed on the 


database server. 
. The Informix identity column keyword is SERIAL8. 


. Informix stored procedures cannot return values. 


nA A W N 


effectively simulating an identity column. 
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ME 


. The MySQL identity column keyword is AUTO_INCRE 


NT. 


. Postgres sequence object can be used to provide default values for primary key columns, 


6. Postgres has a native construct called rules that can be used to effectively simulate triggers 
and instead-of-triggers. It also supports the use of triggers/instead-of-triggers written in a 
variety of procedural programming languages. 


Current Time Stamp Statements 


The following table lists SQL statements used to retrieve the current date and time by database: 


Database Current Time Stamp Statement ANSI-Compliant 


IBM DB2 UDB SELECT (CURRENT TIMESTAMP) FROM SYSIBM.SYSDUMMY1 FETCH FIRST 1ROW No 
ONLY 


Informix IDS SELECT FIRST 1 (CURRENT YEAR TO FRACTION(5)) FROM INFORMIX.SYSTABLES No 


MSSQL SELECT (CURRENT_TIMESTAMP) Yes 
MySQL SELECT (CURRENT_TIMESTAMP) Yes 
Oracle SELECT (SYSDATE) FROM SYS.DUAL No 
PostgreSQL SELECT (CURRENT_TIMESTAMP) Yes 
Sybase ASE SELECT GETDATE() No 


Stored Procedure and Function JDBC Call Syntaxes 


The following table lists the SQL syntax for calling a stored procedure or function. This is useful 
for formatting procedure and function calls in embedded SQL statements. 


Database Stored Procedure/Function JDBC Call Syntax 


IBM DB2 UDB {call schema-name.procedure-name(parameter-list)} 


Informix IDS EXECUTE [PROCEDURE | FUNCTION] schema-name.procedure-name(parameter-list) 
MSSQL EXECUTE schema-name.procedure-name(parameter-list) 

MySQL (NA) 

Oracle CALL schema-name.procedure-name(parameter-list) 

PostgreSQL SELECT schema-name.procedure-name(parameter-list) 

Sybase ASE EXECUTE schema-name.procedure-name(parameter-list) 


Left Outer Join Operators 


The following table lists outer join operators by database. 


Database Left Outer Join Operator Ansi-Compliant 
IBM DB2 UDB LEFT OUTER JOIN Yes 
Informix IDS LEFT OUTER JOIN Yes 
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Database Left Outer Join Operator Ansi-Compliant 
MSSQL *= No 

MySQL LEFT OUTER JOIN Yes 

Oracle (+) No 
PostgreSQL LEFT OUTER JOIN Yes 

Sybase ASE *= No 


NOTE: Oracle supports the ANSI-compliant left outer join operator LEFT OUTER JOIN as of version 10g. 


Undelimited Identifier Case-Sensitivity 


Database Case-Sensitive? 
IBM DB2 UDB No 
Informix IDS No 
MSSQL No 
MySQL Yes 
Oracle No 
PostgreSQL No 
Sybase ASE Yes 


Supported Transaction Isolation Levels 


Database None Read Read Repeatable Serializable URL 
Uncommitted Committed Read 

IBM DB2 UDB 0 X Xx" X Setting JDBC Transaction Isolation 
Levels (http://publib.boulder.ibm.com/ 
infocenter/db2help/index.jsp?topic=/ 
com.ibm.db2.udb.doc/ad/tjvjdiso.htm) 

MySQL (InnoDB Table Type) 0 X X x" InnoDB Transaction Isolation Levels 
(http://dev.mysql.com/doc/mysql/en/ 
innodb-transaction-isolation.html) 

Oracle 0 0 x" 0 JDBC Transaction Optimization (http:// 
www.oracle.com/technology/oramag/ 
oracle/02-jul/o42special_jdbc.html) 

PostgreSQL 0 02 x! 02 Transaction Isolation (http:// 


' This is the default isolation level for this database. 
2 Can be set, but it is aliased to a supported isolation level. 
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www.postgresql.org/docs/current/ 
static/transaction-iso.html) 


Commit Keywords 


The following table identifies the commit keywords for supported databases: 


Database Commit Keyword 
IBM DB2 UDB COMMIT 
Informix IDS = COMMIT WORK! 
MSSQL GO 

MySQL COMMIT 

Oracle COMMIT 
PostgreSQL COMMIT 

Sybase ASE GO 


'For logging and ANSI-compliant databases. Non-logging databases do not support transactions. 


IBM DB2 Universal Database (UDB) 


The following table lists properties for this database. 


Property Value 

Current Timestamp SELECT (CURRENT TIMESTAMP) FROM SYSIBM.SYSDUMMY1 FETCH FIRST 1 ROW ONLY 
Statement 

Stored Procedure/ {call schema-name.procedure-name(parameter-list)} 


Function Call Syntax 


Case-Sensitive? No 


Commit Keyword COMMIT 


Left Outer Join Operator LEFT OUTER JOIN 


Dynamic Defaults 


The following table lists database compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name 
Current Timestamp current-timestamp-stmt 
Statement: 


Timestamp Translator class: time-translator-class 


Value 


SELECT (CURRENT TIMESTAMP) FROM 
SYSIBM.SYSDUMMY1 FETCH FIRST 1 ROW ONLY 


com.novell.nds.dirxml.driver.jdbc.db.DB2Timestamp 
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Known Issues 


+ The timestamp format is proprietary. 


See “Known Issues” on page 119. 


Informix Dynamic Server (IDS) 


The following table lists properties for this database. 


Property Value 

Current Timestamp SELECT FIRST 1 (CURRENT YEAR TO FRACTION(5)) FROM INFORMIX.SYSTABLES 
Statement 

Stored Procedure/ EXECUTE [PROCEDURE | FUNCTION] schema-name.procedure-name(parameter-list) 
Function Call Syntax 

Case-Sensitive? No 

Commit Keyword COMMIT WORK! 


Left Outer Join Operator LEFT OUTER JOIN 


'For logging and ANSI-compliant databases. Non-logging databases do not support transactions. 


Dynamic Defaults 


The following table lists database compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 
Current Timstamp current-timestamp-stmt SELECT FIRST 1 (CURRENT YEAR TO FRACTION(5)) FROM 
Statement: INFORMIX.SYSTABLES 


Known Issues 


+ NUMERIC or DECIMAL columns cannot be used as primary keys unless the scale (that is, the 
number of digits to the right of the decimal point) is explicitly set to 0 when the table is 
created. By default, the scale is set to 255. 


Microsoft SQL Server 


The following table lists properties for this database. 


Property Value 


Current Timestamp Statement SELECT (CURRENT_TIMESTAMP) 


Stored Procedure/Function Call Syntax EXECUTE schema-name.procedure-name(parameter-list) 


Case-Sensitive? No 
Commit Keyword GO 
Left Outer Join Operator *= 
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Dynamic Defaults 


The following table lists database compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 
Add default values on insert? add-default-values-on-view-insert true 


Left outer-join operator: left-outer-join-operator *= 


MySQL 

The following table lists properties for this database. 
Property Value 
Current Timestamp Statement SELECT (CURRENT_TIMESTAMP) 


Stored Procedure/Function Call Syntax (NA) 


Case-Sensitive? Yes 
Commit Keyword COMMIT 
Left Outer Join Operator LEFT OUTER JOIN 


Dynamic Defaults 


The following table lists database compatibility parameters that are dynamically configured at 
runtime for this database. 


Display Name Tag Name Value 
Supports schemas in metadata supports-schemas-in-metadata-retrieval false 
retrieval? 


Known Issues 


* TIMESTAMP columns, when updated after being initially set to 0 or NULL, are always set to 
the current date and time. To compensate for this behavior, we recommend that you map 
eDirectory Time and Timestamp syntaxes to DATETIME columns. 


Oracle 
The following table lists properties for this database. 
Property Value 
Current Timestamp Statement SELECT (SYSDATE) FROM SYS.DUAL 


Stored Procedure/Function Call Syntax CALL schema-name.procedure-name(parameter-list) 


Case-Sensitive? 


No 
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Property Value 


Commit Keyword COMMIT 


Left Outer Join Operator (+) 


Dynamic Defaults 


The following table lists database compatibility parameters that are implicitly set at runtime by this 
product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 

Left outer-join operator left-outer-join-operator (+) 

Exclude filter expression exclude-table-filter BIN\$.{22}==\$0 

Lock statement generator class  lock-generator-class com.novell.nds.dirxml.driver.jdbc.db.lock.OraLoc 
kGenerator 


NOTE: The default exclusion filter is intended to omit dropped tables visible in Oracle 10g from the 
synchronization schema (i.e., database objects visible to this product at runtime). 


Limitations 


+ LONG, LONG RAW and BLOB columns cannot be referenced in a trigger. 


You can’t reference columns of these types using the : NEW qualifier in a trigger, including 
instead-of-triggers. 


PosgreSQL 
The following table lists properties for this database. 
Property Value 
Current Timestamp Statement SELECT (CURRENT_TIMESTAMP) 


Stored Procedure/Function Call Syntax SELECT schema-name.procedure-name(parameter-list) 


Case-Sensitive? No 
Commit Keyword COMMIT 
Left Outer Join Operator LEFT OUTER JOIN 


Known Issues 


+ PostgreSQL does not support <check-object-password> events. Authentication is 
controlled by manually inserting entries into the pg_hba.conf file. 
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Sybase Adaptive Server Enterprise (ASE) 


The following table lists properties for this database. 
Property Value 
Current Timestamp Statement SELECT GETDATE() 


Stored Procedure/Function Call Syntax EXECUTE schema-name.procedure-name(parameter-list) 


Case-Sensitive? 


Yes 


Commit Keyword 


GO 


Left Outer Join Operator 


w 


Dynamic Defaults 


The 


following table lists database compatibility parameters that are implicitly set at runtime by this 


product. These settings should not be explicitly overridden. 


Display Name Tag Name Value 

Current timestamp statement current-timestamp-stmt SELECT GETDATE() 

Left outer-join operator left-outer-join-operator *= 

Timestamp Translator class time-translator-class com.novell.nds.dirxml.driver.jdbc.db.SybaseTimestamp 


Known Issues 


+ 


Padding and truncation of binary values. 


In order to ensure ANSI-compliant padding and truncation behavior for binary values, binary 
column types (other than IMAGE) must be exactly the size ofthe eDirectory attribute that maps 
to them, constrained NOT NULL, and added to the Publisher and Subscriber Creation policies. 
If they are constrained NULL, trailing zeros, which are significant to eDirectory, will be 
truncated. If binary columns exceed the size of their respective eDirectory attributes, extra Os 
will be appended to the value. 


The recommended solution is to only use the IMAGE data type when synchronizing binary 
values. 


DATETIME fractions of a second are rounded. 


Sybase Timestamps are at best accurate to 1/300th of a second (approximately.003 seconds). 
The database server will round to the nearest 1/300" of a second as opposed to the nearest 1/ 
1000" of a second (.001 seconds or 1 millisecond). 


Timestamp formats are proprietary. 


See “Known Issues” on page 119 


Supported Databases 119 


120 IDM Driver for JDBC Implementation Guide 


Using the Association Utility 


This section contains information on using the association utility. The utility is designed to 
normalize associations of objects associated under the 1.0 or later versions of this product. It also 
provides several other features designed to simplify driver administration. 


This version of the utility is backwards compatible with all versions of this product back to version 
1.0 and supersedes all previous versions. 


Understanding the Utility 


This utility supports seven independent operations: 
1. List objects associated with a driver (default) 
2. List objects with multiple associations to a driver 
3. List objects with invalid associations to a driver 
An association is invalid if: 


+ It is malformed. (For example, the association is missing the schema RDN, missing the 
table RDN, or the schema keyword is misspelled.) 


+ It contains database identifiers that do not map to identifiers in the target database. (For 
example, an association includes a mapping to a table that does not exist.) 


+ It maps to no row or multiple rows. An association is broken if it doesn’t map to a row. 
Also, associations aren't unique ifthey map to more than one row. 


4. List objects that need to be normalized 


+ A normalized association is valid, correctly ordered, and uses the correct case. Normal 
case 1s uppercase for case-insensitive databases and mixed case for case-sensitive 
databases. 


5. Normalize object associations listed by the previous operation 
6. List object associations to be modified 


+ Allows for global replacement of schema, table, and column names based on search 
criteria. 


7. Modify object associations listed by the previous operation 


The following table lists the operations and whether they are read-only or write. 


Operation Read-Only vs. Write 
1. List objects associated with a driver Read-only 
2. List objects with multiple associations to a driver Read-only 
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Operation Read-Only vs. Write 


3. List objects with invalid associations to a driver Read-only 
4. List objects that need to be normalized Read-only 
5. Normalize object associations listed by the previous Write 
operation 

6. List object associations to be modified Read-only 
7. Modify object associations listed by the previous Write 
operation 


Before You Begin 


Modifying associations can potentially cause problems. If associations are corrupted, Identity 
Manager ceases to function, so you should use write operations only when necessary. To avoid 
unintentional association corruption, this utility creates an undo Idiff file for all write operations. 


You should review the following cautions before using the utility: 


¢ This utility, like the driver, assumes database identifiers are undelimited (unquoted and 
contain no special characters). 


+ It is extremely important that all object associations related to a driver be updated together. 


+ In order to see all of the objects associated with a particular driver, this utility should be 
run on the Identity Manager server associated with a particular driver instance. 


¢ All of the objects associated with a particular driver must be contained by the LDAP 
search base. 


NOTE: To ensure complete containment, we recommend that you use your tree's root container as 
the search base. 


+ Make sure the JDBC URL of the target database supplied to this utility is the same as the one 
used by the driver. Pointing this utility at a case-insensitive database when the database is 
actually case-sensitive might result in associations being normalized to the wrong case. 


+ Because this utility is run locally, it uses an unsecured connection, so the eDirectory LDAP 
server must be temporarily configured to accept clear text passwords. Depending upon the 
third-party JDBC driver you are using, the database connection established by this utility 
might be insecure. 


NOTE: We recommend changing the driver’s authentication password on the database after running this 
utility. 
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This utility must be run once for each instance of the driver installed on an IDM server. There is 
a batch file association.bat or shell script association. sh (depending upon your 
platform) in the install-dir\jdbc\util directory that will start the utility. 


A properties file is provided for each supported database. They can be found in the install- 
dir\jdbc\util directory. 
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Database Properties Filename 
IBM DB2 Universal Database properties db2.txt 
Informix Dynamic Server properties ifx ansi.txt1 


properties ifx log.txt 
properties ifx no log.txt 


Microsoft SQL Server properties ms.txt 
MySQL properties my.txt 
Oracle properties ora.txt 
PostgreSQL properties pg.txt 
Sybase Adaptive Server Enterprise properties syb.txt 


"This utility does not work with Informix ANSI-compliant databases. 


NOTE: For more information on how to run the utility from the command line, refer to run.bat in the install- 
dir\tools\util directory. 


1 Stop the driver. 
2 Identify and remove extraneous associations (operations 2 and 3). 


No object associated by this product should have multiple associations. Extraneous 
associations must be removed manually on a per object basis. Operation 3 might help you 
identify which of the multiple associations is actually valid. After this is known, the 
extraneous associations can probably be discarded. 


3 Identify and fix invalid associations (operation 3 and possibly operations 6 and 7). 


As a general rule, if the problem is isolated, edit each invalid association manually. If the 
problem is repetitive and affects a large number of associations, consider using operations 6 
and 7. This utility can replace bad identifiers on a global basis, but cannot insert or remove 
them where they do not already exist. 


4 Normalize associations (operations 4 and 5). 


Editing Associations 


This utility requires two parameters (oldRDN and newRDN) for operations 6 and 7. This section 
explains how to use these parameters. 


The first value is the search criterion and the second is the replacement value. The wildcard 
character * can be used under certain scenarios to generalize the search criterion or replacement 
value. 


Three types of search and replace operations are possible: 
1. Schema name replacement 
Wildcards are supported on the right side only. For example, 
+ Replace schema old with schema new 
oldRDN: schema=old 


newRDN: schema=new 
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2. Table name replacement 
Wildcards are not supported. For example, 
+ Replace table old with table new: 
oldRDN: table=old 
newRDN: table=new 
3. Column name replacement 


Wildcards are required on the right side, but they aren’t supported on the left side. For 
example, 


+ Replace column old with column new: 
oldRDN: old=* 


newRDN: new=* 
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Uninstalling the IDM Driver for JDBC 


In this section, you will learn how to uninstall a driver and its corresponding database objects. 


IMPORTANT: We recommend installing and uninstalling preconfigured drivers and database scripts as a unit. 
To prevent unintentional mismatching, database scripts and preconfigured drivers contain headers with a 
version number, the target database name, and the database version. 


Delete IDM Driver Objects 


When deleting Novell? eDirectory™ objects, you must delete all child objects before you can 
delete a parent object. For example, you must delete all rules and style sheets on the Publisher 
channel before you can delete the Publisher object. Similarly, you must delete both the Publisher 
and Subscriber objects before you can delete the Driver object. 


To remove a driver object from eDirectory: 
1 In Novell iManager, click DirXML Management > Overview. 
2 From Overview, locate the driver set where the driver exists, then click Delete Driver. 


3 Click the Driver you want to delete, then click ok. 


Run the Product Uninstaller 


Uninstallation procedures vary by platform. 


For Windows, from the Control Panel, click on the Add or Remove Programs icon. Select the 
NSure Identity Manager Driver for JDBC and click on the Change/Remove button. Follow the 
uninstallation prompts. 


Execute Database Uninstallation Scripts 


This section provides helps you execute database uninstallation SQL scripts. 
+ “IBM DB2 Universal Database (UDB) Installation” on page 28 
+ “Informix Dynamic Server (IDS) Installation” on page 29 
+ “Microsoft SQL Server Installation” on page 29 
+ “MySQL Uninstallation” on page 126 
+ “Oracle Installation” on page 30 
+ “PostgreSQL Installation” on page 30 
+ “Sybase Adaptive Server Enterprise (ASE) Installation” on page 31 
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IBM DB2 Universal Database (UDB) Uninstallation 


The directory context for DB2 is install-dir\jdbc\sql\db2_udbl\install. 
1 Dropthe idm, indirect and direct operating system user accounts. 


2 Change the name of the administrator account name and password in the installation scripts 
if you haven't already done so. 


3 Using the Command Line Processor (CLP) execute script uninstall.sql. For example: 


db2 -f uninstall.sql 


IMPORTANT: This script won't execute in the Command Center interface beyond version 7. lt utilizes 
the 'V line continuation character which later versions of the Command Center don’t recognize. 


4 Delete the idm_db2. jar file. 


Informix Dynamic Server (IDS) Uninstallation 


The directory context for Informix SQL scripts is install-dir\jdbc\sql\informix_ids\install. 
1 Drop the idm operating system user account. 
2 Start a client such as SQL Editor. 


3 Log on to your server as user informix or another user with DBA (database administrator) 
privileges. By default, the password for informix is informix. 


NOTE: If you execute scripts as a user other than informix, you will need to change all references to 
informix in the install scripts prior to execution. 


4 Ifyou aren’t using the informix account with the default password, change the name of the 
DBA account name and password in the installation scripts if you haven’t already done so. 


5 Open and execute uninstall.sql from either the ansi (transactional, ANSI-compliant), 
log (transactional, non-ANSI-compliant), no log (non-transactional, non-ANSI- 
compliant) subdirectories depending upon which type of database you installed. 


Microsoft SQL Server Uninstallation 


The directory context for Microsoft SQL Server scripts is install-dir\jdbc\sql\mssql\install. 
1 Start a client such as Query Analyzer. 
2 Log on to your database server as user sa. By default, the sa user has no password. 
3 Open and execute the first installation script uninstall.sql. 


NOTE: The execute hotkey in Query Analyzer is F5. 


MySQL Uninstallation 


The directory context for MySQL SQL scripts is install-dir\jdbc\sql\mysql\install. 


1 From a MySQL client, such as mysql, log on as user root or another user with administrative 
privileges. By default, the root user has no password. For example, from the command-line 
execute: 


mysql -u root -p 


2 Execute the uninstallation script uninstall.sql. For example: 
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mysql> \. c:\uninstall.sql 


TIP: Don’t use a semi-colon to terminate this statement. 


Oracle Uninstallation 


The directory context for Oracle SQL scripts is install- 
dir\jdbc\sql\oracle\install. 


1 From an Oracle client, such as SQL Plus, logon as user SYSTEM. By 
default, the password for SYSTEM is MANAGER. 


NOTE: If you execute scripts as a user other than SYSTEM with password 
MANAGER, you will need to change all references to SYSTEM in the scripts prior 
to execution. 


2 Execute the uninstallation script uninstall.sql. For example: 


SQL> @c:\uninstall.sql 


PostgreSQL Uninstallation 


The directory context for PostgreSQL scripts is install- 
dir\jdbc\sql\postgres\install. The directory context for executing Postgres 
commands is postgres-install-dir/pgsql/bin. 


1 From a Postgres client such as psql, logon as user postgres to the idm 
database. By default, the postgres user has no password. For example, 
from the unix command line, execute the command psa]: 

./psql -d idm postgres 


2 From inside psql, execute the script uninstall.sql. For example: 


idm=# \i uninstall.sql 


3 Drop the database idm. For example, from the unix command line, 
execute the command dropdb: 


./dropdb idm 


4 Remove or comment out entries for the idm user from the pg_hba. conf 
file. For example: 


host idm idm 255.255.255.255 255.255.255.0 


5 Restart the Postgres server to effect changes made to the pg_hba. conf 
file. 
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Sybase Adaptive Server Enterprise (ASE) Uninstallation 


The directory context for Sybase SQL scripts is install-dir\jdbc\sql\sybase_ase\install. 


1 From a Sybase client, such as isql, logon as user sa and execute the installation script 


uninstall.sql. By default, the sa account has no password. For example, from the 
command line, execute: 


isql -U sa -P -i uninstall.sql 
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Best Practices 


The following section lists important best practices for using the driver. You can find additional 
information in Chapter 4, "Configuring the IDM Driver for JDBC,” on page 33 and Chapter 5, 
“Advanced Configuration,” on page 67. 


+ 


” 


For direct synchronization, you must prefix one or more view column names with "pk 
(case-insensitive). 


For both direct and indirect synchronization, ensure that you use different primary key column 
names between logical database classes. 


Primary key values placed in the event log table key field should be delimited (that is, 
double-quoted) if they contain the following characters: 


sa ha eS 


This is usually only an issue if the primary key column is a binary type. 


When eDirectory™ is the authoritative source of primary key values, GUID rather than CN is 
recommended for use as a primary key. Unlike CN, GUID is single-valued and does not 
change. 


Foreign key columns that link child and parent tables should always be omitted from 
publication triggers. 


Tracing should be turned off in a production environment. 


Do not include primary key columns in publication triggers if they are static (that is, they do 
not change.) 


You should place the jdbc: type="query" attribute value on all embedded SELECT 
statements, and the jdbc: type="update" attribute value on all embedded INSERT, 
UPDATE and DELETE statements. 


For performance and security reasons, you should run the driver remotely whenever possible. 
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FAQ 


The following section contains answers to some common questions you might encounter as you 
install or configure the driver. These include: 


+ "Why can't the driver see my tables or views?” on page 131 

+ "How do I synchronize with tables located in multiple schemas?” on page 131 

+ "Why isn't the driver processing rows in the event log table?” on page 132 

+ "Can the driver manage database user accounts?” on page 132 

+ "Can the driver synchronize large binary and string data types?” on page 132 

+ “Why is publication so slow?” on page 132 

+ “Can the driver synchronize multiple classes?” on page 132 

+ “Does the driver support encrypted transport?” on page 132 

+ “How do I map multivalue attributes to single-value database fields?” on page 133 


+ “Why is the driver synchronizing garbage strings?” on page 133 


Why can’t the driver see my tables or views? 


The driver is capable only of synchronizing tables that have explicit primary key constraints and 
views that contain one or more columns prefixed with “pk_” (case-insensitive). These constraints 
are used by the driver to determine which fields should be utilized when constructing associations. 
As such, the driver ignores any unconstrained tables. 


If you are trying to synchronize with tables/views that lack the necessary constraints, you need to 
either add them or synchronize to intermediate tables with the required constraints. 


Another possibility is that the driver lacks the necessary database privileges to see the tables. 
Usually, visibility is determined by the SELECT privilege. 


How do I synchronize with tables located in multiple schemas? 


You’ ll need to either alias the tables into the synchronization schema, synchronize to intermediate 
tables in the synchronization schema and move the data across schema boundaries, use a view, or 
create a virtual schema via the parameter “Table/view name” on page 41. 
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Why isn't the driver processing rows in the event log table? 


There are several explanations for this behavior. First, you should check the perpetrator field 
of the rows in question and make sure the value is set to something other than the driver’s database 
username. The Publisher checks the perpet rator field to detect loopback events if the publisher 
parameter “Allow loopback?” on page 62 is set to Boolean False (the default). When set to 
Boolean False, the Publisher ignores all records where the perpetrator field value is equal to 
the driver’s database username. The driver’s database username is specified using the parameter 
“Authentication ID” on page 36. 


You should also ensure that the record’s status field is set to “N” (new). Records with status 
fields set to something other than ‘N’ will not be processed. Also, make sure to explicitly commit 
changes. Changes are often tentative until explicitly committed. 


Can the driver manage database user accounts? 


Yes, database accounts can be managed using embedded SQL. For more information, refer to 
“Embedding SQL Statements in XDS Events” on page 87. 


Can the driver synchronize large binary and string data types? 


Yes. Large binary and string data types can be subscribed and published. Large binary and string 
data types should be published using query-back event types. For additional information, see 
“Event Types” on page 82. 


Why is publication so slow? 


If the event log table contains a large number of rows, it should be indexed. Example indexes are 
provided in all database installation scripts. The statements used by the driver to maintain the event 
log can be viewed using trace level 3. 


Indexes in the installation scripts can be further refined to enhance publication performance. 
Placing indexes in a different tablespace or physical disk than the event log table will also enhance 
publication performance. 


Furthermore, the parameter “Delete processed rows?” on page 61 should be set to Boolean False 
in a production environment unless processed rows are being periodically moved to another table. 


Can the driver synchronize multiple classes? 


Yes. However, primary key column names must be unique between logical database classes. For 
example, if class] is mapped to table] with primary key column name key/ and class2 is mapped 
to table2 with primary key column name key2, then the name of key/ cannot equal key2. This 
requirement can always be satisfied irrespective of the synchronization model being employed. 


Does the driver support encrypted transport? 
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No. How the driver communicates with a given database is dependent upon the third-party driver 
being used. Some third-party drivers support encrypted transport while others do not. Even if 
encrypted transport is supported, there is no standardized way of enabling encryption between 
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third-party JDBC drivers. The general solution for this problem is to remotely run this product and 
your third-party driver - this allows both to run locally on the database server. All data traveling 
across the network between the DirXML engine and this product will be SSL encrypted. 


Another possibility is to use a type 3 or type 2 third-party JDBC driver. Database middleware and 
client APIs usually provide encrypted transport mechanisms. 


How do I map multivalue attributes to single-value database fields? 


For detailed information on how to map multivalue attributes to single-value database fields, refer 
to "Mapping Multivalue Attributes to Single-Value Database Fields” on page 77. 


Why is the driver synchronizing garbage strings? 


The database and the third-party driver are probably using incompatible character encoding. This 
can be remedied by adjusting the character encoding used by your third-party driver. 


For more information, refer to the Character Encoding Values (http://java.sun.com/j2se/1.5.0/ 
docs/guide/intl/encoding.doc.html) defined by Sun. 
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Supported Data Types 


This product is capable of synchronizing all JDBC 1 data types and a small subset of JDBC 2 data 
types. How JDBC data types map to a database's native data types is third-party driver-dependent. 


The following list includes the supported JDBC 1 java.sql.Types (http://java.sun.com/j2se/1.5.0/ 


docs/api/java/sql/Types.html). 


+ Numeric Types: 


e+ 5 


e+ 4 


ava.sql 


java.sql 
java.sql 
java.sql 
java.sql 
java.sql 
java.sql 
java.sql 


java.sql 


ava.sql 


+ String Types: 


e+ 5 
* 4 
ø 4 


+ Time 


java.sql 
java.sql 


java.sql 


Types: 


java.sql 
java.sql 


java.sql 


* Binary Types: 


e+ 4 


+ 5 


+ 


java.sql 
java.sql 


java.sql 


-Types.! 
-Types.! 
.Types. 

.Types. 
.Types. 
. Types .RE 
. Types. 
. Types. 
. Types. 


. Types 


. Types. 
. Types 


. Types 


. Types. 
. Types. 


. Types. 


. Types. 
. Types 


. Types 


INTEGER 


SMALLINT 


. TINYINT 


CHAR 


+ LONGCHAR 


. VARCHAR 


DATE 


TIME 


BINARY 


. VARBINARY 


. LONGVARBINARY 


The following list includes the supported JDBC 2 java.sql.Types (http://java.sun.com/j2se/1.5.0/ 


docs/api/java/sql/Types.html). 


+ Large Object (LOB) Types: 
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* Java.sql.Types.CLO 


* Java.sql.Types.BLO 


136 IDM Driver for JDBC Implementation Guide 


java.sql.DatabaseMetaData Methods 


This section lists the required and optional java.sql.DatabaseMetaData (http://java.sun.com/j2se/ 
1.5.0/docs/api/java/sql/DatabaseMetaData.html) methods. 


Required JDBC 1 methods: 


+ 


+ 


+ 


+ 


getColumns(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String 
tableNamePattern, java.lang.String columnNamePattern):java.sql.ResultSet 


getPrimaryKeys(java.lang.String catalog, java.lang.String schema, java.lang.String 
table):java.sql. ResultSet 


getTables(java.lang.String catalog, java.lang.String schemaPattern, java.lang.String 
tableNamePattern, java.lang.String[] types):java.sql.ResultSet 


storesLowerCaseldentifiers():boolean 
storesMixedCaseldentifiers():boolean 


storesUpperCaseldentifiers():boolean 


Optional JDBC 1 methods: 


+ 


+ 


+ 


+ 


+ 


dataDefinitionCausesTransactionCommit():boolean 
dataDefinitionIgnoredInTransactions():boolean 
getDatabaseProductName():java.lang. String 
getDatabaseProductVersion():java.lang. String 
getDriverMajorVersion():int 
getDriverMinorVersion():int 
getDriverName():java.lang. String 
getDriverVersion():java.lang.String 


getExportedKeys(java.lang.String catalog, java.lang.String schema, java.lang.String 
table):java.sql. ResultSet 


getMaxStatements():int 
getMaxConnections():int 
getMaxColumnsInSelect():int 


getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, 
String columnNamePattern):java.sql.ResultSet 


getSchemas():java.sql.ResultSet 
getTableTypes():java.sql.ResultSet 
getUserName():java.lang.String 
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+ 


supportsColumnAliasing():bolean 
supportsDataDefinitionAndDataManiuplationTransactions():boolean 
supportsDataManipulationTransactionsOnly():boolean 
supportsLimitedOuterJoins():boolean 
supportsMultipleTransactions():boolean 
supportsSchemasInDataManipulation():boolean 
supportsSchemasInProcedureCalls():boolean 
supportsTransactionIsolationLevel(int level):boolean 


supportsTransactions():boolean 


Optional JDBC 2 methods: 


+ 


supportsBatchUpdates():boolean 


Optional JDBC 3 methods: 


+ 


supportsGetGeneratedKeys():boolean 
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Utilized JDBC Methods 


This section lists the JDBC interface methods (other than java.sql.DatabaseMetaData (http:// 
java.sun.com/j2se/1.5.0/docs/api/java/sql/DatabaseMetaData.html) methods) used by this 
product. Methods are organized by class. Often, third-party JDBC driver vendors list defects or 
known issues by method. This section can be used in collaboration with third-party JDBC driver 
documentation to troubleshoot or anticipate potential interoperability problems. Methods listed in 
this appendix are ordered as follows: 


l. 


java.sql.DriverManager (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 
DriverManager.html) 


. java.sql.CallableStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 


CallableStatement.html) 


. java.sql.Connection (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection) 
. java.sql.PreparedStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 


PreparedStatement.html) 


. java.sql.ResultSet (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ResultSet.html) 
. java.sql.ResultSetMetaData (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 


ResultSetMetaData.html) 


. java.sql.Statement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Statement.html) 
. Java.sql.Timestamp (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Timestamp.html) 


The following table lists java.sql.DriverManager (http://java.sun.com/j2se/1.5.0/docs/api/java/ 
sql/DriverManager.html) methods used by this product: 


Method Signature JDBC Version Required? 
getConnection(String url, java.util.Properties info):java.sql.Connection 1 yes! 
getConnection(String url, java.util.Properties info):java.sql.Connection 1 yes! 
setLogStream(java.io.PrintStream out):void 1 no 


lOne method or the other. 
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The following table lists java.sql.CallableStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/ 


sql/CallableStatement.html) methods used by this product: 


Method Signature 


JDBC Version Required? 


getBigDecimal(int parameterIndex, int scale):java.math.BigDecimal 1 yes 
getBoolean(int parameterlndex):boolean 1 yes 
getBoolean(String parameterName):boolean 3 no 
getByte(int parameterlndex):byte 1 yes 
getByte(String parameterName):byte 3 no 
getBytes(int parameterlndex):byte[] 1 yes 
getBytes(String parameterName):bytel] 3 no 
getDate(int parameterlndex):java.sql.Date 1 yes 
getDate(String parameterName):java.sql.Date 3 no 
getDouble(int parameterIndex):double 1 yes 
getDouble(String parameterName):double 3 no 
getFloat(int parameterlndex):float 1 yes 
getFloat(String parameterName):float 3 no 
getint(int parameterIndex):int 1 yes 
int getInt(String parameterName) 3 no 
getLong(int parameterlndex):long 1 yes 
getLong(String parameterName):long 3 no 
getShort(int parameterlndex):short 1 yes 
getShort(String parameterName):short 3 no 
getString(int parameterIndex):String 1 yes 
getString(String parameterName):String 3 no 
getTime(int parameterIndex):java.sql. Time 1 yes 
getTime(String parameterName):java.sql.Time 3 no 
getTimestamp(int parameterIndex):java.sql. Timestamp 1 yes 
getTimestamp(String parameterName):java.sql.Timestamp 3 no 
registerOutParameter(int parameterlndex, int sqlType):void 1 yes 
wasNull():boolean 1 yes 


IDM Driver for JDBC Implementation Guide 


The following table lists java.sql.Connection (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 
Connection) methods used by this product: 


Method Signature JDBC Version Required? 
close():void 1 yes 
commit():void 1 no 
createStatement():java.sql.Statement 1 yes 
getAutoCommit():boolean 1 no 
getMetaData():java.sql.DatabaseMetaData 1 yes 
getTransactionlsolation():int 1 no 
getWarnings():java.sql.SQLWarning 1 no 
isClosed():boolean 1 no 
prepareCall(String sql):java.sql.CallableStatement 1 no 
prepareStatement(String sql):java.sql.PreparedStatement 1 yes 
rollback():void 1 no 
setAutoCommit(boolean autoCommit):void 1 no 
setTransactionlsolation(int level):void 1 no 


The following table lists java.sql.PreparedStatement (http://java.sun.com/j2se/1.5.0/docs/api/java/ 
sql/PreparedStatement.html) methods used by this product: 


Method Signature JDBC Version Required? 
clearParameters() :void 1 no 
execute():boolean 1 yes 
executeQuery():java.sql.ResultSet 1 yes 
executeUpdate():int 1 yes 
setBigDecimal(int parameterlndex, java.math.BigDecimal x):void 1 yes 
setBoolean(int parameterlndex, boolean x):void 1 yes 
setByte(int parameterIndex, byte x):void 1 yes 
setBytes(int parameterlndex, byte x[]): void 1 yes 
setDate(int parameterlndex, java.sql.Date x):void 1 yes 
setDouble(int parameterIndex, double x):void 1 yes 
setFloat(int parameterlndex, float x):void 1 yes 
setInt(int parameterIndex, int x):void 1 yes 
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Method Signature JDBC Version Required? 


setLong(int parameterlndex, long x):void 1 yes 
setNull(int parameterIndex, int sqlType):void 1 yes 
setShort(int parameterlndex, short x):void 1 yes 
setString(int parameterindex, String x):void 1 yes 
setTime(int parameterlndex, java.sql.Time x):void 1 yes 
setTimestamp(int parameterlndex, java.sql.Timestamp x):void 1 yes 


The following table lists java.sql.ResultSet (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 
ResultSet.html) methods used by this product: 


Method Signature JDBC Version Required? 
close():void 1 yes 
getBigDecimal(int columnindex, int scale):java.math.BigDecimal 1 yes 
getBigDecimal(String columnName, int scale):java.math.BigDecimal 1 yes 
getBinaryStream(int columnIndex):java.io.InputStream 1 yes 
getBinaryStream(String columnName)java.io.InputStream 1 yes 
getBoolean(int columnIndex):boolean 1 yes 
getBoolean(String columnName):boolean 1 yes 
getByte(int columnIndex):byte 1 yes 
getByte(String columnName):byte 1 yes 
getBytes(int columnIndex):byte[] 1 yes 
getBytes(String columnName):byte[] 1 yes 
getDate(int columnIndex):java.sql.Date 1 yes 
getDate(String columnName)java.sql.Date 1 yes 
getFloat(int columnIndex):float 1 yes 
getFloat(String columnName):float 1 yes 
getInt(int columnIndex):int 1 yes 
getInt(String columnName):int 1 yes 
getLong(int columnIndex):long 1 yes 
getLong(String columnName):long 1 yes 
getMetaData():java.sql.ResultSetMetaData 1 no 
getShort(int columnIndex):short 1 yes 
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Method Signature 


JDBC Version Required? 


getShort(String columnName):short 1 yes 
getString(int columnIndex):String 1 yes 
getString(String columnName): String 1 yes 
getTime(int columnIndex):java.sql. Time 1 yes 
getTime(String columnName):java.sql. Time 1 yes 
getTimestamp(int columnIndex):java.sql. Timestamp 1 yes 
getTimestamp(String columnName):java.sql. Timestamp 1 yes 
getWarnings():java.sql.SQLWarning 1 no 


The following table lists java.sql.ResultSetMetaData (http://java.sun.com/j2se/1.5.0/docs/api/ 


java/sql/ResultSetMetaData.html) methods used by this product: 


Method Signature 


JDBC Version Required? 


getColumnCount():int 1 no 
getColumnName(int column):String 1 no 
getColumnType(int column):int 1 no 


The following table lists java.sql.Statement (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 


Statement.html) methods used by this product: 


Method Signature 


JDBC Version Required? 


addBatch(java.lang.String sql):void 2 no 
clearBatch():void 2 no 
clearWarnings():void 1 no 
close():void 1 yes 
execute(java.lang.String sql):boolean 1 yes 
executeBatch():int[] 2 no 
executeUpdate(String sql):int 1 yes 
executeQuery(String sql):java.sql.ResultSet 1 yes 
getGeneratedKeys():java.sql.ResultSet 3 no 
getMoreResults():boolean 1 no 
getResultSet():java.sql.ResultSet 1 yes 
getUpdateCount():int 1 no 
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Method Signature 


getWarnings():java.sql. SQLWarning 


JDBC Version Required? 


1 


no 


The following table lists java.sql. Timestamp (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/ 


Timestamp.html) methods used by this product: 


Method Signature 


JDBC Version Required? 


getNanos():int 1 yes 
getTime():long 1 yes 
setNanos(int n):void 1 yes 
setTime(long time):void 1 yes 
toString ():String 1 yes 
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Third-Party JDBC Driver Descriptor DTD 


This section contains the DTD for third-party JDBC descriptor files. 


<?xml version="1.0" 


ncoding="UTF-8"?> 


<!ELEMENT actions (exec-sql | check-for-closed-connection | fetch-metadata | rollback)*> 
<!ELEMENT add-default-values-on-view-insert (#PCDATA) > 
<!ELEMENT authentication (sql-state | error-code | sql-state-class | error-code-range | 
actions) *> 
<!ELEMENT check-for-closed-connection EMPTY> 
<!ELEMENT column-position-comparator (#PCDATA) > 
<!ELEMENT connection-properties (property*) > 
<!ELEMENT connectivity (sql-state | error-code | sql-state-class | error-code-range | 
actions) *> 
<!ELEMENT current-timestamp-stmt (#PCDATA) > 
<!ELEMENT error-code (value) > 
<!ATTLIST error-code 
description CDATA #IMPLIED 
> 
<!ELEMENT error-code-range (from, to)> 
<!ATTLIST error-code-range 
description CDATA #IMPLIED 
> 
<!ELEMENT errors (connectivity | authentication | retry | fatal) *> 
<!ELEMENT exclude-table-filter (#PCDATA) > 
<!ELEMENT exec-sql (#PCDATA) > 
<!ELEMENT fatal (sql-state | error-code | sql-state-class | error-code-range | actions) *> 
<!ELEMENT fetch-metadata EMPTY> 
<!ELEMENT from (#PCDATA) > 
<!ELEMENT function-return-method (#PCDATA) > 
<!ELEMENT handle-stmt-results (#PCDATA) > 
<!ELEMENT identity (name?, target-database?, jdbc-type?, jdbc-class?)> 
<!ELEMENT import (#PCDATA) > 
<!ELEMENT imports (import*)> 
<!ELEMENT include-table-filter (#PCDATA) > 
<!ELEMENT jdbc-class (#PCDATA)> 
<!ELEMENT jdbc-driver (imports?, identity, (metadata-override | connection-properties | sql- 
type-map | options | errors)%)> 
<!ELEMENT jdbc-type (#PCDATA) > 
<!ELEMENT key (#PCDATA) > 
<!ELEMENT left-outer-join-operator (#PCDATA) > 
<!ELEMENT lock-generator-class (#PCDATA) > 
<!ELEMENT metadata-override (supports-schemas-in-procedure-calls?)> 
<!ELEMENT minimal-metadata (#PCDATA) > 
<!ELEMENT name (#PCDATA) > 
<!ELEMENT options (lock-generator-class | supports-schemas-in-metadata-retrieval | time- 
translator-class | column-position-comparator | use-manual-transactions | minimal-metadata | 
transaction-isolation-level | use-single-connection | exclude-table-filter | include-table- 
filter left-outer-join-operator | current-timestamp-stmt | add-default-values-on-view-insert 


| reuse-statements 


function-return-method | handle-stmt-results)+> 
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<!ELEMENT property (key, value)> 
<!ELEMENT retry (sql-state | error-code | sql-state-class | error-code-range | actions)*> 
<!ELEMENT reuse-statements (#PCDATA) > 
<!ELEMENT rollback EMPTY> 
<!ELEMENT sql-state (value)> 
<!ATTLIST sql-state 
description CDATA #IMPLIED 


> 

<!ELEMENT sql-state-class (value)> 

<!ATTLIST sql-state-class 
description CDATA #IMPLIED 


> 
<! ELEM 
<!ELEM 
<!ELEM 


ENT sql-type-map (type*)> 
ENT supports-schemas-in-metadata-retrieval (#PCDATA) > 
ENT supports-schemas-in-procedure-calls (#PCDATA) > 

<!ELEMENT target-database (#PCDATA) > 

<!ELEMENT time-translator-class (#PCDATA) > 

<!ELEMENT to (#PCDATA) > 
E 
E 
E 
E 
E 


<!ELEMENT transaction-isolation-level (#PCDATA) > 
<!ELEMENT type (from, to)> 

<!ELEMENT use-manual-transactions (#PCDATA) > 
<!ELEMENT use-single-connection (#PCDATA) > 
<!ELEMENT value (#PCDATA) > 
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Third-Party JDBC Driver Descriptor Import DTD 


This section contains the DTD for third-party JDBC descriptor import files. 


<?xml version="1.0" encoding="UTF-8"?> 
<!ELEMENT actions (exec-sql | check-for-closed-connection | fetch-metadata | rollback)*> 
<!ELEMENT add-default-values-on-view-insert (#PCDATA) > 


<!ELEMEN 


authentication (sql-state | error-code | sql-state-class | error-code-range | 


actions) *> 


<!ELEMENT check-for-closed-connection EMPTY> 

<!ELEMENT column-position-comparator (#PCDATA) > 

<!ELEMENT connection-properties (property*) > 

<!ELEMENT connectivity (sql-state | error-code | sql-state-class | error-code-range | 


actions) *> 
<!ELEMENT current-timestamp-stmt (#PCDATA) > 


error-code (value) > 
error-code 


description CDATA ff IMPLIED 


error-code-range (from, to)> 
error-code-range 


description CDATA #IMPLIED 


errors (connectivity | authentication | retry | fatal)*> 

T exclude-table-filter (#PCDATA) > 

exec-sql (#PCDATA) > 

fatal (sql-state | error-code | sql-state-class | error-code-range | actions) *> 
[ fetch-metadata EMPTY> 

T from (#PCDATA) > 

T function-return-method (#PCDATA) > 


handle-stmt-results (#PCDATA) > 


<!ELEMENT 
<!ATTLIST 
> 
<!ELEMEN 
<!ATTLIST 
> 
<!ELEMEN 
<!ELEMENT 
<! ELEMENT 
<!ELEMENT 
<!ELEMENT 
<!ELEMENT 
<! ELEMENT 
<!ELEMEN 
<! ELEMEN 
<! ELEMEN 


include-table-filter (#PCDATA)> 


jdbc-driver (metadata-overrid | connection-properties | sql-type-map | options 


<!ELEMENT key (#PCDATA)> 

<!ELEMENT left-outer-join-operator (#PCDATA)> 

<!ELEMENT lock-generator-class (#PCDATA)> 

<!ELEMENT metadata-override (supports-schemas-in-procedure-calls?)> 

<!ELEMENT minimal-metadata (#PCDATA)> 

<!ELEMENT options (lock-generator-class | supports-schemas-in-metadata-retrieval | time- 
translator-class | column-position-comparator | use-manual-transactions | minimal-metadata | 
transaction-isolation-level | use-single-connection | exclude-table-filter | include-table- 
filter left-outer-join-operator | current-timestamp-stmt | add-default-values-on-view-insert 
| reuse-statements | function-return-method | handle-stmt-results) *> 

<!ELEMENT property (key, value)> 

<!ELEMENT retry (sql-state | error-code | sql-state-class | error-code-range | actions) *> 
<!ELEMENT reuse-statements (#PCDATA) > 

<!ELEMENT rollback EMPTY> 

<!ELEMENT sql-state (value) > 


<!ATTLIST sql-state 
description CDATA #IMPLIED 
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> 


<!ELEMENT sql-state-class (value)> 
<!ATTLIST sql-state-class 
description CDATA #IMPLIED 


> 

<!ELE 
<!ELE 
<!ELE 


NT sql-type-map (type*)> 
NT supports-schemas-in-metadata-retrieval 


<!ELE 


NT time-translator-class (#PCDATA) > 


<!ELE 


<!ELE 


NT transaction-isolation-level (#PCDATA) > 


<!ELE 


NT type (from, to)> 


<!ELE 


NT use-manual-transactions (#PCDATA) > 


<!ELE 
<!ELE 
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E 
E 
E 
E 
MENT to (#PCDATA) > 
E 
E 
E 
E 
E 


NT use-single-connection (#PCDATA) > 
NT value (#PCDATA) > 
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(#PCDATA) > 
NT supports-schemas-in-procedure-calls (#PCDATA) > 


This section contains the DTD for database descriptor files. 


Database Descriptor DTD 


<?xml version="1.0" encoding="UTF-8"?> 

<!ELEMENT add-default-values-on-view-insert (#PCDATA) > 

<!ELEMENT column-position-comparator (#PCDATA) > 

<!ELEMENT current-timestamp-stmt (#PCDATA) > 

<!ELEMENT database (imports?, identity, options?)> 

<!ELEMENT exclude-table-filter (#PCDATA) > 

<!ELEMENT function-return-method (#PCDATA) > 

<!ELEMENT handle-stmt-results (#PCDATA) > 

<!ELEMENT include-table-filter (#PCDATA) > 

<!ELEMENT identity (name?, regex-name?, regex-version?) > 

<!ELEMENT import (#PCDATA) > 

<!ELEMENT imports (import*) > 

<!ELEMENT left-outer-join-operator (#PCDATA) > 

<!ELEMENT lock-generator-class (#PCDATA) > 

<!ELEMENT minimal-metadata (#PCDATA) > 

<!ELEMENT name (#PCDATA) > 

<!ELEMENT options (lock-generator-class | supports-schemas-in-metadata-retrieval | time- 
translator-class | column-position-comparator | use-manual-transactions | minimal-metadata | 
transaction-isolation-level | use-single-connection | exclude-table-filter | include-table- 
filter left-outer-join-operator | current-timestamp-stmt | add-default-values-on-view-insert 
| reuse-statements | function-return-method | handle-stmt-results)*> 

<!ELEMENT regex-name (#PCDATA)> 

<!ELEMENT regex-version (#PCDATA) > 

<!ELEMENT reuse-statements (#PCDATA) > 

<!ELEMENT supports-schemas-in-metadata-retrieval (#PCDATA) > 

<!ELEMENT time-translator-class (#PCDATA) > 

<!ELEMENT transaction-isolation-level (#PCDATA) > 

<!ELEMENT use-manual-transactions (#PCDATA) > 

<!ELEMENT use-single-connection (#PCDATA) > 
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<?xml version="1.0" 


Database Descriptor Import DTD 


This section contains the DTD for database descriptor import files. 


ncoding="UTF-8"?> 


<!ELEMENT add-default-values-on-view-insert (#PCDATA) > 

<!ELEMENT column-position-comparator (#PCDATA) > 

<!ELEMENT current-timestamp-stmt (#PCDATA) > 

<!ELEMENT exclude-table-filter (#PCDATA) > 

<!ELEMENT function-return-method (#PCDATA) > 

<!ELEMENT handle-stmt-results (#PCDATA) > 

<!ELEMENT include-table-filter (#PCDATA) > 

<!ELEMENT database (options?)> 

<!ELEMENT left-outer-join-operator (#PCDATA) > 

<!ELEMENT lock-generator-class (#PCDATA) > 

<!ELEMENT minimal-metadata (#PCDATA) > 

<!ELEMENT options (lock-generator-class | supports-schemas-in-metadata-retrieval | time- 
translator-class | column-position-comparator | use-manual-transactions | minimal-metadata | 
transaction-isolation-level use-single-connection | exclude-table-filter | include-table- 
filter left-outer-join-operator | current-timestamp-stmt | add-default-values-on-view-insert 
| reuse-statements | function-return-method | handle-stmt-results) *> 

<!ELEMENT reuse-statements (#PCDATA) > 

<!ELEMENT supports-schemas-in-metadata-retrieval (#PCDATA) > 

<!ELEMENT time-translator-class (#PCDATA) > 

<!ELEMENT transaction-isolation-level (#PCDATA) > 

<!ELEMENT use-manual-transactions (#PCDATA) > 

<!ELEMENT use-single-connection (#PCDATA) > 
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